Pharaoh - Your AI breaks things it can't see

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

Annotations only declare read-only safety. The description adds critical behavioral context: sub-3-second performance on full graph queries, specific return cluster types (parallel consumers, fan-in duplication, signature twins), and tier limitations (Pharaoh Pro vs preview). It could be elevated to 5 with mention of caching or idempotency, but the tier disclosure is crucial behavioral context.

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?

Perfectly structured with clear headings (CALL THIS WHEN, RETURNS, WHY NOT JUST READ FILES, TIER). Every sentence earns its place—the tier warning is essential for handling truncated preview responses, and the performance claim (<3 seconds) justifies using this over multiple file reads.

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?

Despite lacking an output schema, the description thoroughly documents return values: cluster types, file paths, line numbers, and evaluation context. For a complex graph analysis tool, this provides sufficient information to interpret results and decide on consolidation actions.

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 contains zero parameters. Per rubric guidelines, zero parameters establishes a baseline score of 4. The description appropriately requires no parameter clarification since the tool operates as a global analysis query.

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 opens with a specific verb-resource combination ('Find code that does the same work') and enumerates exact structural patterns detected (parallel consumers, duplicated call chains, competing DB access). This clearly distinguishes the tool from siblings like get_unused_code (dead code detection) or search_functions (symbol lookup).

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 explicit 'CALL THIS WHEN:' section provides four distinct scenarios including pre-development checks and refactoring planning. The 'WHY NOT JUST READ FILES' section effectively contrasts this against manual file inspection and generic read tools, guiding the agent away from inefficient alternatives.

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