fix: improve tool descriptions with explicit cross-references #694
Conversation
Update descriptions on manage_gameobject, find_gameobjects, and manage_components to use explicit "NOT for X — use Y tool" phrasing and include full resource URIs. This helps LLMs route to the correct tool instead of guessing based on parameter names. Each tool now clearly states: - What it does (positive) - What it does NOT do and which tool/resource to use instead (negative) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reviewer's GuideRefines MCP tool descriptions for GameObject CRUD, search, and component management to add explicit negative routing and cross-references to related tools and resources, without changing any logic or parameters. Flow diagram for choosing between GameObject and component toolsflowchart TD
start[Determine_intent_for_scene_operation]
start --> q_search{Need_to_search_for_existing_GameObjects?}
q_search -->|Yes| use_find[Use_find_gameobjects_tool]
q_search -->|No| q_crud{Need_to_create_modify_delete_or_move_a_GameObject?}
use_find --> res_use_gameobject["Then_use_mcpforunity://scene/gameobject/{id}_for_full_data"]
res_use_gameobject --> res_use_components["Optionally_use_mcpforunity://scene/gameobject/{id}/components_for_component_details"]
q_crud -->|Yes| use_manage_go[Use_manage_gameobject_tool]
q_crud -->|No| q_component{Need_to_add_remove_or_set_properties_on_components?}
q_component -->|Yes| use_manage_components[Use_manage_components_tool]
q_component -->|No| unknown[Operation_not_covered_by_these_tools]
use_manage_go --> delegate_search[For_searching_use_find_gameobjects]
use_manage_go --> delegate_components[For_component_management_use_manage_components_or_components_resource]
use_manage_components --> delegate_go_crud[For_creating_or_deleting_GameObjects_use_manage_gameobject]
use_manage_components --> use_components_resources[For_reading_use_components_resources]
use_components_resources["mcpforunity://scene/gameobject/{id}/components_or_/component/{name}"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughThree MCP tool descriptions are updated to provide clearer guidance on their specific purposes and capabilities. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
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. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- Consider aligning the wording between the tool description and the error message in
manage_gameobject(e.g., consistently using the same phrasing for search vs. component management) so the guidance is uniform across touchpoints. - The expanded descriptions are quite long; you might want to extract common URI guidance into a shared constant or helper to avoid duplication and potential drift between tools if these endpoints change.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Consider aligning the wording between the tool description and the error message in `manage_gameobject` (e.g., consistently using the same phrasing for search vs. component management) so the guidance is uniform across touchpoints.
- The expanded descriptions are quite long; you might want to extract common URI guidance into a shared constant or helper to avoid duplication and potential drift between tools if these endpoints change.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
Not against this @HivemindMinion but is there any objective way to know that this change makes it better? |
|
Good question — here's the reasoning with sources. The short version: Anthropic, OpenAI, and GitHub's own MCP team all document that explicit negative routing in tool descriptions ("NOT for X, use Y instead") measurably reduces tool misselection by LLMs. Key data points:
Why it matters for unity-mcp specifically: We have three tools that all operate on GameObjects — Objective measurement: The most objective test would be building a confusion matrix like GitHub did — running N prompts through each model and measuring how often it selects the right tool before vs after the description changes. Happy to set that up if it'd be useful, but the existing research strongly suggests this pattern works. |
|
@HivemindMinion curiosity, are you a person or a bot? If person, English speaker? There's no wrong answer - and it doesn't affect your contribution. Your response was very ChatGPT-esque, just wondering if there's a reason for ChatGPT vs your own words |
|
Human behind a bot. :)
…On Sat, Feb 7, 2026, 8:36 PM Marcus Sanatan ***@***.***> wrote:
*msanatan* left a comment (CoplayDev/unity-mcp#694)
<#694 (comment)>
@HivemindMinion <https://github.com/HivemindMinion> curiosity, are you a
person or a bot? If person, English speaker?
There's no wrong answer - and it doesn't affect your contribution. Your
response was very ChatGPT-esque, just wondering if there's a reason for
ChatGPT vs your own words
—
Reply to this email directly, view it on GitHub
<#694 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/B2POQSEDMNDJF7AIJTMWM3D4K2OMBAVCNFSM6AAAAACUI53YAOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNRVHE4DAOBVGE>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
@HivemindMinion can you resolve the merge conflict? Happy to merge after |
3 participants
Description
Updates tool descriptions on
manage_gameobject,find_gameobjects, andmanage_componentsto use explicit negative routing ("NOT for X — use Y tool") and include full resource URIs.LLMs pick which tool to use based on the
descriptionfield in the MCP schema. When descriptions are vague about tool boundaries, LLMs guess wrong. This change makes the routing unambiguous.Type of Change
Changes Made
manage_gameobject— Added explicit "NOT for searching" / "NOT for component management" with tool names and resource URIs:find_gameobjects— Added cross-references to downstream resources and back tomanage_gameobject:manage_components— Added cross-references to read resources and back tomanage_gameobject:Testing/Screenshots/Recordings
All 563 Python tests pass. Description-only changes — no parameter or logic modifications.
Documentation Updates
descriptionstrings were updated — these are embedded in the MCP schema that LLMs see.Related Issues
Companion to #693 (vestigial param removal). Together these two changes address the LLM tool routing confusion that caused ~46 failed calls in a single session.
Summary by Sourcery
Clarify and tighten MCP tool boundaries and routing between GameObject CRUD, search, and component-management tools by improving their descriptions and cross-references.
Enhancements:
Summary by CodeRabbit