godotlens-mcp

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes what the tool does (finds references), what it returns (list of locations with file, line, character), and important implementation details (ZERO-BASED coordinates). However, it doesn't mention potential limitations like performance considerations with large projects or whether it works across all file types.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences that each add value: the core functionality, the return format, and the usage context. It's front-loaded with the main purpose and contains zero wasted words. The 'IMPORTANT' callout effectively highlights critical implementation details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analysis tool with 3 documented parameters and no output schema, the description provides good context about what the tool does and when to use it. It explains the return format (list of locations) and critical coordinate system details. The main gap is the lack of output schema, but the description compensates reasonably well by describing the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any additional parameter information beyond what's in the schema. It mentions 'symbol' but doesn't clarify that the parameters identify the symbol's location rather than the symbol name itself. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Find all references to a symbol'), the scope ('across the entire project'), and distinguishes from siblings like gdscript_definition or gdscript_declaration by focusing on usage locations rather than definitions. It uses precise language that goes beyond just restating the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'Essential for impact analysis before refactoring: "What code uses this symbol?"' This provides clear context about the tool's purpose in development workflows and distinguishes it from other symbol-related tools that might focus on definitions or declarations rather than references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.