gograph_orphans

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

Exceeds annotations by describing full BFS reachability, freshness checks, retry behavior for precise graphs, and confirms no side effects. No contradiction with readOnlyHint or idempotentHint.

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?

Concise, well-structured, front-loaded with purpose, and every sentence adds value. Uses clear sections (WHEN TO USE, NOT TO USE, RETURNS).

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?

Given zero parameters and no output schema, the description fully covers behavior, use cases, and return value format. Annotations cover safety profile; description adds algorithmic and refresh context.

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?

Input schema has zero parameters, so no parameter documentation needed. Description appropriately focuses on tool behavior rather than missing parameters.

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?

Description explicitly states 'Find functions and methods unreachable from runtime roots' with specific scoping (main/init, tests, HTTP routes, exports) and method (BFS reachability). Distinguishes from sibling tools like gograph_usages and gograph_callers.

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?

Provides explicit 'WHEN TO USE' (code cleanup, dead-code audits) and 'NOT TO USE' (checking single symbol's usages, with alternatives named).

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