tool_find_references

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

With no annotations, the description carries the full burden and does well: it explains it parses jump and call statements to build a reference map, and that bad targets are detected. It stops short of noting analysis cost/limits or whether it reads the whole project, but behavior is substantially disclosed for a read-only analysis tool.

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 core purpose is front-loaded in the first sentence, followed by a compact explanation of mechanism and use cases. The Args/Returns blocks are structured and skimmable; slightly verbose but every sentence carries information.

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?

With no output schema and no annotations, the description still tells the agent what the return dict contains (name, defined, definition, is_screen, callers, caller_count) and documents both required parameters. Nothing needed to invoke or interpret the tool is missing.

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?

Schema description coverage is 0%, so the description must compensate, and it does: project_path is documented as the absolute path to the Ren'Py project root, and name as the label/screen name to search for with a concrete example ("arrow_round"). Format and expected value are clear, though the accepted name formats (label vs screen syntax) could be tightened.

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?

States a specific verb+resource ('Find all jump/call references to a label or screen across the project') and scopes it clearly against siblings like tool_list_labels and tool_list_definitions by emphasizing references/callers rather than definitions. An agent can distinguish the tool's job without opening the schema.

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?

Gives concrete when-to-use contexts: refactoring (find all callers before renaming), detecting dead code, and catching missing jump targets. This is clear usage context, though it does not explicitly name an alternative sibling tool or state when-not to use it.

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