fix: improve tool descriptions with explicit cross-references (rebased #694)

[dsarno]

Summary

Rebased version of #694 by @HivemindMinion to resolve merge conflicts after #688 landed on beta.

Original PR: #694
Original author: @HivemindMinion / @HivemindOverlord

• Updates tool descriptions on manage_gameobject, find_gameobjects, and manage_components to use explicit "NOT for X — use Y tool" phrasing
• Includes full resource URIs for cross-references
• Description-only changes, no parameter or logic modifications

Conflict resolution: took #694's description text over #688's overlapping changes in manage_gameobject.py (which is the whole point of #694).

Summary by Sourcery

Clarify responsibilities and cross-references among scene tooling functions for GameObject search, GameObject CRUD, and component management without changing behavior or parameters.

Enhancements:

• Improve find_gameobjects description to spell out supported search modes and point to resource URIs for full GameObject and component data.
• Clarify manage_components description with explicit action list, required inputs, and resource URIs for reading component data, and cross-reference manage_gameobject for GameObject-level CRUD.
• Refine manage_gameobject description and error message to explicitly state what it should not be used for and direct callers to find_gameobjects and manage_components for search and component operations.

Documentation:

• Update tool-level documentation strings so callers can more easily choose the correct tool and resource URI for scene, GameObject, and component operations.

Summary by CodeRabbit

• Documentation
  • Enhanced descriptions for game object search, component management, and game object management tools with improved guidance on supported actions, required parameters, and relevant data access endpoints.
  • Updated error messages to clearly direct users to the appropriate tool for each type of operation, significantly improving overall discoverability and ease of platform use.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Refines the textual descriptions and guidance for the Unity MCP tools find_gameobjects, manage_components, and manage_gameobject to make their responsibilities, cross-references, and recommended usage patterns explicit, without changing any behavior or parameters.

Flow diagram for selecting between find_gameobjects, manage_gameobject, manage_components, and component resources

flowchart TD
    A[Need to work with a GameObject or its components?] --> B{What is the primary goal?}

    B --> C[Search for GameObjects by name, tag, layer, component type, or path]
    B --> D[Create, modify, delete, duplicate, or move a GameObject]
    B --> E[Add, remove, or set properties on components]
    B --> F[Read component data only]

    C --> G[Use tool: find_gameobjects]
    G --> H["Then use resource: mcpforunity://scene/gameobject/{id} for full GameObject data"]
    G --> I["Or use resource: mcpforunity://scene/gameobject/{id}/components for component details"]

    D --> J[Use tool: manage_gameobject]
    J --> J1[Actions: create, modify, delete, duplicate, move_relative]

    E --> K{Is this about components or GameObjects themselves?}
    K --> L[Components only]
    K --> M[GameObjects lifecycle or structure]

    L --> N[Use tool: manage_components]
    N --> N1[Actions: add, remove, set_property]

    M --> J

    F --> O["Use resource: mcpforunity://scene/gameobject/{id}/components"]
    F --> P["Or resource: mcpforunity://scene/gameobject/{id}/component/{name} for a single component"]

    subgraph Explicit_NOT_for_guidance
      J -. NOT for searching: use find_gameobjects .-> G
      J -. NOT for component management: use manage_components or components resources .-> N
      N -. NOT for creating or deleting GameObjects: use manage_gameobject .-> J
      G -. For CRUD operations on GameObjects: use manage_gameobject .-> J
    end

Loading

File-Level Changes

Change	Details	Files
Clarify usage and cross-references for the GameObject search tool.	Rephrased the tool description to enumerate supported search dimensions (name, tag, layer, component type, path). Emphasized that the tool returns only instance IDs in a paginated fashion. Added explicit guidance to use mcpforunity://scene/gameobject/{id} and .../{id}/components URIs for full GameObject and component data respectively. Documented that CRUD-style modifications should be done via the manage_gameobject tool instead.	Server/src/services/tools/find_gameobjects.py
Clarify usage and cross-references for the component management tool.	Reworded the tool description to explicitly list supported actions (add, remove, set_property) and required inputs (target, component_type). Strengthened guidance that reading component data should be done via the components URIs rather than this tool. Added an explicit cross-reference that GameObject creation/deletion is handled by manage_gameobject, not this tool.	Server/src/services/tools/manage_components.py
Clarify usage boundaries, cross-references, and error messaging for the GameObject management tool.	Updated the tool description to use explicit "NOT for ..." phrasing to distinguish this tool from find_gameobjects and manage_components. Consolidated component reading guidance into the description, pointing to the components resource URI. Adjusted the missing-parameter error message for action to restate valid actions and give clearer direction to use find_gameobjects for searching and manage_components for component operations.	Server/src/services/tools/manage_gameobject.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Updated decorator descriptions and error messages across three tool files (find_gameobjects, manage_components, manage_gameobject) to provide expanded usage guidance, clarify search and component management capabilities, and redirect users to appropriate tools for specific operations.

Changes

Cohort / File(s)	Summary
Tool Documentation Updates Server/src/services/tools/find_gameobjects.py, Server/src/services/tools/manage_components.py	Expanded decorator descriptions to clarify search/management criteria, specify return types (instance IDs with pagination), and reference related tools and endpoints for accessing full object and component data.
Manage GameObject Guidance Server/src/services/tools/manage_gameobject.py	Updated decorator description to explicitly exclude search and component management operations, redirecting users to find_gameobjects and manage_components tools. Updated error message to align with new guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• Make it easier to add tools #301: Updates to the mcp_for_unity_tool decorator descriptions directly reference the decorator mechanism introduced in this PR.
• fix: remove vestigial find/component params from manage_gameobject #693: Parallel changes to manage_gameobject tool description that redirect users to dedicated find and component management tools.
• fix: add parameter validation to manage_gameobject tool #296: Modifies the manage_gameobject tool with parameter typing and validation changes that complement the clarified tool responsibilities in this PR.

Suggested reviewers

• msanatan
• justinpbarnett

Poem

🐰 The tools now speak with clarity bright,
Each description gleaming, precise and right,
Find what you seek, manage with care,
Redirecting lost users to their proper lair!

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Hey - I've left some high level feedback:

• The emphasis style in the user-facing strings is a bit inconsistent (e.g., NOT for searching, For READING, To SEARCH, capitalized COMPONENTS); consider normalizing the tone and casing across all tool descriptions and error messages for a more uniform UX.
• Since the descriptions now reference alternative tools and resources, it may be worth standardizing whether you mention the full mcpforunity://... URI vs. just the tool name (e.g., manage_gameobject, manage_components) so that cross-references are consistent between tools.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The emphasis style in the user-facing strings is a bit inconsistent (e.g., `NOT for searching`, `For READING`, `To SEARCH`, capitalized `COMPONENTS`); consider normalizing the tone and casing across all tool descriptions and error messages for a more uniform UX.
- Since the descriptions now reference alternative tools and resources, it may be worth standardizing whether you mention the full `mcpforunity://...` URI vs. just the tool name (e.g., `manage_gameobject`, `manage_components`) so that cross-references are consistent between tools.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}