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

Annotations declare read-only safety (readOnlyHint=true), so description adds value by detailing return structure ('path from entry point to function', 'classification') since no output schema exists, and disclosing tier constraints ('free tier receives a preview') that affect behavior. No contradictions with annotations.

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?

Well-structured with clear visual hierarchy: purpose statement, CALL THIS WHEN bullets, RETURNS specification, and TIER notice. Each section earns its place, though the Pharaoh Pro marketing language ('free tier receives a preview') is slightly verbose compared to purely technical descriptions.

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?

Complete for a zero-parameter analysis tool. Compensates for missing output schema by describing return values (reachability boolean, path, classification). Tier limitation disclosure is essential contextual data. Sufficiently distinguishes from sibling analysis tools via specific scope.

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?

Zero parameters present, triggering baseline 4 per rules. Schema is '{}' (empty object), and description appropriately avoids mentioning parameters since none exist. Schema coverage is trivially 100% with no params to document.

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?

Specific verb ('Check') + resource ('functions') + precise scope ('from production entry points'). Explicitly lists entry point types (API endpoints, CLI, cron, etc.), clearly differentiating from siblings like 'get_unused_code' (which finds dead code without path analysis) and 'get_codebase_map' (general structure).

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?

Excellent 'CALL THIS WHEN:' section with four specific scenarios (post-feature implementation, PR review, dead code cleanup, pre-PR checks). Provides clear contextual triggers. Lacks explicit 'when-not' or named alternative tools to earn a 5, but the scenario specificity strongly implies appropriate usage contexts.

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

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

Annotations only declare read-only safety. Description adds critical behavioral context: 5-hop depth limit, specific return structure (risk levels, grouped callers by module, HTTP endpoints, cron jobs, DB operations), and explains it traces transitive dependencies automatically.

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?

Excellent structure with clear headings (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES). Front-loaded purpose statement. Every section earns its place; no redundancy with structured fields.

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 no output schema, description comprehensively details return values (risk assessment, affected callers, endpoints, cron jobs, DB operations) and explains the analysis depth. Sufficient for a complex static analysis tool.

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?

Zero parameters per schema, establishing baseline 4. Description implicitly clarifies the tool operates on code entities (functions/files/modules) from context, though no explicit parameter documentation is needed for an empty schema.

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?

Opens with specific verb+resource ('Check what breaks') and scope (functions, files, modules). The 'BEFORE' qualifier and 'up to 5 hops deep' distinguish it from simple grep/call lookup tools like search_functions or check_reachability.

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?

Explicit 'CALL THIS WHEN' section lists four specific trigger scenarios (refactoring, safety checks, PR review, risk assessment). The 'WHY NOT JUST READ FILES' section explicitly contrasts with file-reading alternatives, explaining when this tool's transitive analysis is necessary.

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

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

Substantial value beyond annotations. Details return structure (modules with LOC, dependency graph with weights/bidirectional warnings, hot files defined as 'most changed in last 90 days', HTTP endpoints). Does not contradict readOnlyHint=true. Lacks operational details like caching, rate limits, or performance cost of generating full map.

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?

Well-structured with clear headers (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES). Every section earns its place. Front-loaded with critical guidance 'Call this FIRST'. Length is justified by complexity of the tool's output and usage context.

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?

Excellent completeness for a zero-parameter tool. Compensates for lack of output schema by detailing RETURNS section with specific data structures (weights, bidirectional warnings, 90-day windows). Explains scope and limitations of the knowledge graph sufficiently for agent to use effectively.

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?

Zero parameters present (baseline 4). Schema is empty object. Description correctly omits parameter discussion since none exist, but signals this is a simple invocation via 'Call this FIRST' and lack of filtering options implied by 'no user/workspace filtering' in sibling examples.

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?

Clear specific action ('get the full architecture') and resource ('codebase knowledge graph'). Explicitly distinguishes from siblings by positioning as the FIRST call and contrasting with 'reading files one-by-one' and manual directory traversal.

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?

Exceptional explicit guidelines with 'CALL THIS WHEN:' bullet points covering 4 specific scenarios. Includes 'WHY NOT JUST READ FILES' section that explicitly contrasts with the manual alternative approach, explaining the value add (dependency relationships, change frequency).

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

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.

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

Annotations declare readOnlyHint=true (safe operation), while the description adds substantial behavioral context: it details the three-tier match system (HIGH/MEDIUM/LOW with definitions), discloses additional return data (shared module structure, environment variables), explains the preview limitations of the free tier, and notes that matches include 'clear action guidance'.

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?

Excellent structure with clear section headers (CALL THIS WHEN, RETURNS, PREREQUISITE, TIER, EXAMPLES). Information is front-loaded and dense—every sentence serves a specific purpose, from use-case triage to output format explanation to business logic constraints.

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 comprehensively documents the return structure (three match tiers with definitions, additional shared data types), prerequisites, and tier limitations. For a read-only analysis tool with clear annotations, this provides sufficient context for correct invocation and expectation management.

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?

With zero parameters, the baseline score is 4 per evaluation rules. The description provides implicit parameter guidance by specifying 'Use repo names, not paths' and referencing the two repositories to be compared, though the input schema is empty.

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 ('Compare') and clear resource scope ('two repositories'), detailing exact analysis targets ('code duplication, structural overlap, and shared patterns'). It effectively distinguishes from single-repo siblings like `get_codebase_map` and `search_functions` by emphasizing cross-repo comparison.

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?

Contains an explicit 'CALL THIS WHEN' section listing four specific scenarios (copy-paste detection, package extraction planning, structure comparison, pre-refactor auditing). It also states prerequisite requirements ('Both repos must be mapped via pharaoh add') and input format constraints ('Use repo names, not paths'), providing clear invocation boundaries.

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

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

Annotations declare readOnlyHint=true; description adds valuable behavioral context beyond safety: details return structure (components with props/usage counts, tokens, anti-patterns) and important scope limitation (screen/page components excluded by default). Does not mention performance characteristics or caching behavior.

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?

Excellent structure with clear visual hierarchy: main directive, CALL THIS WHEN, RETURNS, EXAMPLES, and WHY NOT sections. Every sentence earns its place; examples are concrete and relevant. No redundant repetition of schema or annotation data.

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?

Highly complete for a parameter-free tool. Compensates for missing output schema by explicitly detailing what the tool returns (components, tokens, anti-patterns) and what it excludes. Complexity is appropriate for the tool's scope.

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?

Zero parameters present; schema is empty object. Baseline score of 4 applies as per rules for parameter-free tools. No parameter documentation needed.

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?

Excellent specificity: verb 'discover' + resource 'design system' + clear scope (components, tokens, anti-patterns). The description clearly distinguishes this from general codebase analysis tools like get_codebase_map by focusing specifically on UI components and design tokens.

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?

Outstanding guidance with explicit 'CALL THIS WHEN' section listing 4 specific scenarios (creating React/Vue components, finding canonical patterns, locating tokens, detecting anti-patterns). Includes 'WHY NOT JUST READ FILES' section explaining when to use this tool versus manual file exploration.

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

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

Annotations only declare read-only safety; description adds substantial behavioral context: token cost (~2K), specific return payload structure (file count, LOC, function signatures, dependency graphs, DB access, endpoints, cron jobs, env vars), and performance comparison to manual exploration (10K-40K tokens saved). No contradictions with annotations.

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?

Though lengthy, content is densely valuable with zero redundancy. Structured with clear headers (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES) and bullet points enabling scannability. Length is justified by absence of output schema and zero parameters requiring description to carry full semantic load.

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?

Compensates excellently for missing output schema by exhaustively documenting return value structure (listing 10+ specific data points from file counts to vision spec alignment). With zero parameters and no output schema, the description provides complete contractual information necessary for invocation.

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, triggering baseline score of 4 per rubric. Description correctly omits parameter discussion as none exist, focusing instead on behavioral contract and return value semantics.

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?

Opens with specific verb+resource ('Get everything... about a module') and scope constraint ('BEFORE modifying'). Distinguishes from siblings like get_codebase_map (high-level architecture) and search_functions (single function level) by emphasizing comprehensive surface-area analysis for pre-modification safety.

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?

Contains explicit 'CALL THIS WHEN:' section with four specific triggering contexts (changing code, writing PRDs, checking dependents, viewing resources). Includes 'WHY NOT JUST READ FILES' subsection that explicitly contrasts with manual exploration, establishing clear alternative avoidance criteria.

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

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

Annotations establish readOnlyHint=true and destructiveHint=false, confirming this is a safe read operation. The description adds valuable behavioral context beyond these annotations by specifying the return format ('markdown'), content structure ('Relevant documentation sections'), and reference links ('links to the full page on pharaoh.so/docs').

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 uses a clear three-part structure: value proposition ('Stuck, confused...'), usage criteria ('CALL THIS WHEN'), and output specification ('RETURNS'). Every sentence earns its place with zero redundancy despite the structured formatting.

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 the tool's simplicity (no parameters, read-only) and lack of output schema, the description compensates adequately by explicitly stating what content is returned and its format. Minor gap: it doesn't explicitly characterize the search/retrieval mechanism (semantic vs keyword), though this is implied by the troubleshooting 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 (empty object). Per evaluation rules, 0 parameters warrants a baseline score of 4. The description appropriately does not fabricate parameter semantics where none exist.

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 tool retrieves help documentation using specific verbs ('Get help from Pharaoh's documentation') and explicitly scopes it to setup, tools, security, and pricing. It effectively distinguishes itself from technical code-analysis siblings like get_blast_radius and get_codebase_map by positioning as the product support/documentation resource.

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 includes an explicit 'CALL THIS WHEN:' section with five specific scenarios (troubleshooting unexpected results, setup instructions, 'how does Pharaoh do X' questions, etc.). This provides clear contextual boundaries that prevent confusion with the server's numerous code analysis tools.

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

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

Adds crucial behavioral context beyond readOnlyHint=true: describes detailed return format (risk score 0-1, critical/high/medium/low tiers, complexity metrics, churn data) and discloses tier limitations (Pharaoh Pro vs free preview). No contradictions with annotations.

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?

Well-structured with clear headers (CALL THIS WHEN, RETURNS, TIER). Every section serves distinct purpose. Tier warning about 'preview' vs 'full data' is necessary for user expectations despite being commercial context.

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?

No output schema exists, but RETURNS section comprehensively describes output structure (scores, tiers, complexity metrics). Tier limitations disclosure ensures users understand data completeness constraints. Appropriate for 0-parameter analysis tool.

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, establishing baseline 4 per rubric. Description correctly requires no parameter elaboration since the tool appears to analyze the current context or entire codebase without specific inputs.

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?

Opens with specific verb 'Score' + resource 'functions' + clear concept 'regression risk — how likely a change here breaks production.' Distinguished from sibling get_blast_radius by focusing on quantified risk scoring rather than just mapping dependencies.

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?

Exceptional 'CALL THIS WHEN' section lists 4 specific contextual triggers: before modifying functions, during code review, planning refactors, and after regressions. Provides concrete workflow integration points that clearly separate it from analysis tools like search_functions or get_test_coverage.

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

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

While annotations declare readOnlyHint=true, the description adds crucial behavioral context: it details the return format (per-module summary with file-level test presence and high-complexity function gaps) and discloses tier limitations (Pharaoh Pro vs. free preview constraints). This warns the agent that free tier users receive limited data requiring summarization and upgrade links.

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?

Well-structured with clear sections: purpose statement, usage guidelines (bulleted), return value description, and tier limitations. The tier section is slightly verbose but contains necessary business logic. Information is front-loaded with the core purpose appearing immediately.

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 compensates by detailing what the tool returns (per-module summaries, file coverage status, high-complexity function gaps). It also addresses subscription tier constraints, providing sufficient context for a zero-parameter read-only analysis tool.

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 input schema contains zero parameters, which establishes a baseline score of 4. The description appropriately makes no mention of parameters since none exist, requiring no additional semantic clarification beyond the empty schema.

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 tool 'See[s] which modules and files have test coverage and which don't' and specifies it returns a 'Per-module test coverage summary.' This specifically targets test coverage analysis, distinguishing it from sibling tools like get_codebase_map or get_module_context which handle general code structure rather than test-specific gaps.

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?

Contains an explicit 'CALL THIS WHEN:' section with three distinct scenarios: before writing tests, during code review, and when planning test strategy. These concrete use cases provide clear guidance on when this tool is appropriate versus other analysis tools in the suite.

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

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

Beyond annotations (readOnlyHint=true), the description details the three-tier classification system (Dead/Likely Dead/Alive), explains the dual-layer detection methodology ('graph reachability + text reference'), and discloses the 'Pharaoh Pro' tier limitation requiring the AI to summarize previews. No contradictions with annotations.

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?

Description uses clear section headers ('CALL THIS WHEN:', 'RETURNS:', 'TIER:') creating scannable structure. It is front-loaded with the core purpose, and every section earns its place—including the tier warning which is critical for the agent to handle partial responses correctly.

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 provided, the description compensates by fully documenting the three-tier return classification and file path evidence. It also covers the free-tier limitation (preview mode), ensuring the agent understands operational constraints before invocation.

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, establishing a baseline of 4. The description correctly omits parameter discussion, as none exist. Context signals confirm 100% schema coverage (vacuously true for empty schemas).

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 ('Find') and resource ('dead code/functions'), immediately clarifying scope with 'not reachable from any production entry point.' This distinguishes it from siblings like check_reachability (which likely validates specific functions) and get_blast_radius (impact analysis) by defining the specific graph-unreachability detection use case.

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 'CALL THIS WHEN:' section provides four explicit, actionable scenarios (cleaning up, before adding code, code review, post-refactor). However, it lacks explicit named alternatives (e.g., 'use check_reachability instead for single-function verification') or explicit 'when not to use' exclusions, keeping it from a 5.

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

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

Annotations declare readOnlyHint=true. Description adds significant behavioral context: aggregation behavior (scattered docs across directories), cross-referencing logic (spec-to-code alignment), and return structure (grouped by type with title/section ID/implementation status). Also discloses tier limitation (Pharaoh Pro preview). Does not mention error conditions or caching behavior.

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?

Well-structured with clear headers (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES, TIER). Front-loaded with purpose statement. Length is appropriate given complexity and lack of output schema, though slightly verbose. Every section serves distinct purpose.

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?

No output schema exists, but description fully compensates with RETURNS section detailing grouping logic and field structure. Covers purpose, usage scenarios, return format, alternative comparison, and commercial constraints (Pro tier). Complete for a metadata/aggregation tool with good annotations.

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?

Zero parameters present. Per rubric, 0 params = baseline 4. The EXAMPLES section provides calling patterns ('Is there a PRD for...', 'What does the CLAUDE.md say...') which help clarify usage without 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?

Opens with specific verb 'Get' and clearly identifies resource as 'documented intent — CLAUDE.md files, PRDs, roadmaps, skill specs'. Distinguishes value proposition (understand WHY code exists) from siblings like get_codebase_map or get_pharaoh_docs. The 'WHY NOT JUST READ FILES' section explicitly differentiates from alternative approaches.

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?

Contains explicit 'CALL THIS WHEN:' section with four specific scenarios (implementing features, understanding design intent, verifying requirements, code review). Includes concrete EXAMPLES with four natural language queries. The 'WHY NOT JUST READ FILES' provides clear selection guidance against direct file reading alternatives.

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

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

While annotations declare readOnlyHint=true/destructiveHint=false, the description adds significant operational context: it discloses the cross-referencing algorithm ('cross-references the entire spec tree against the function graph'), performance characteristics ('gaps that would take an hour to find manually surface in seconds'), and business-tier constraints ('Pharaoh Pro — free tier receives a preview'). It does not disclose specific complexity thresholds or rate limits, preventing a 5.

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 well-structured with clear visual headers (CALL THIS WHEN, RETURNS, EXAMPLES) that facilitate parsing. It is front-loaded with the core purpose. While lengthy, the EXAMPLES section (4 queries) and tier warning earn their place by clarifying intended use cases and business constraints. Minor redundancy exists between the bullet points and examples, preventing a perfect 5.

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: 'Two lists' with specific fields (function names, complexity scores, file paths, spec references). It also explains the tier-based limitation (preview vs. full data) which affects the output. For a complex analysis tool with zero parameters, this provides sufficient completeness, though specific complexity thresholds could have been mentioned.

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 calibration rules, 0 params yields a baseline score of 4. The description appropriately requires no parameter clarification since the tool operates as a global analysis requiring no filters.

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 dual-purpose statement: 'Find what's missing — specs without code AND complex code without specs.' This clearly defines the tool's unique value proposition (bidirectional gap analysis) and distinguishes it from siblings like get_vision_docs (which likely just retrieves documents) or get_codebase_map (structural overview). The scope is precisely bounded to spec-to-code alignment.

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?

Contains an explicit 'CALL THIS WHEN' section with four specific scenarios (planning work, finding undocumented functions, auditing alignment, answering 'what's left'). Critically, it includes 'WHY NOT JUST READ FILES' which explicitly contrasts the tool against the manual alternative, demonstrating when NOT to use manual file reading. This provides clear contextual guardrails for tool selection.

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

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

Annotations indicate non-readonly, non-destructive operation. Description adds valuable context: operation takes 1-3 minutes, repo becomes available to all Pharaoh users (shared visibility), and constraint that only public repos are supported. No contradictions with annotations.

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?

Clear two-section structure with purpose statement front-loaded. 'CALL THIS WHEN' bullets are scannable. No redundant text—every sentence provides concrete guidance on scope, timing, or sibling differentiation.

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?

Comprehensive for a zero-parameter trigger tool: covers prerequisites (public repo, not already mapped), side effects (global visibility), timing expectations, and follow-up actions (use get_codebase_map). Minor gap: does not mention error handling for private repos or rate limiting.

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 with 100% description coverage. Baseline score of 4 applies per rubric. Description implies GitHub URL is required but does not explicitly document parameter mechanics, which could confuse agents about how the repo identifier is passed.

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 uses specific verb 'Map' with clear resource 'public GitHub repository' and scope 'into Pharaoh.' Explicitly distinguishes from sibling get_codebase_map by stating this is for repos 'that isn't in Pharaoh yet' and directing users to get_codebase_map after mapping completes.

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?

Contains explicit 'CALL THIS WHEN:' section with three specific trigger conditions, including clear alternation logic with get_codebase_map ('doesn't show a well-known public repo'). Directly maps user phrases like 'map this repo' to tool invocation.

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

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

The description mentions mutation actions (Toggle PR Guard, trigger graph refreshes, manage billing) which aligns correctly with readOnlyHint=false. It also notes the ability to open the visual dashboard externally, adding context beyond the annotations. Does not mention rate limits or auth requirements, but annotations cover the safety profile (destructiveHint=false).

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?

Well-structured with the core purpose front-loaded in the first sentence, followed by the explicit 'CALL THIS WHEN' directive. While the bullet list is lengthy, each item represents a distinct use case that helps the LLM route correctly among the 20+ sibling tools. No wasted sentences.

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 the tool handles multiple account functions (billing, PR Guard, graph refresh) with no output schema, the description adequately covers the functional scope. It could benefit from hinting at return structure (e.g., 'returns subscription details'), but the comprehensive use-case coverage compensates.

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 (empty properties object). Per calibration rules, 0 params = baseline 4. The description appropriately does not invent parameters, implying the tool manages state contextually or interactively.

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 opening sentence uses specific verbs (View, manage, Toggle, trigger) with clear resources (subscription status, billing, PR Guard, graph refreshes). It effectively distinguishes from siblings—all other tools are code analysis functions (get_codebase_map, search_functions, etc.), while this is explicitly the account/billing management interface.

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?

Contains an explicit 'CALL THIS WHEN:' section with 7 detailed bullet points covering subscription checks, payment updates, plan verification, PR Guard toggling, graph refreshes, and dashboard access. This provides explicit routing guidance for when to select this tool over the code-analysis siblings.

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

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

Annotations cover safety (readOnly: false, destructive: false), while the description adds valuable outcome context ('Your feedback directly improves result quality'). It explains the 'WHY' behind the tool's existence, though it could enhance further by describing the feedback mechanism (e.g., whether it's batched, immediate, or triggers notifications).

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 three distinct sections: opening condition statement, bulleted triggers ('CALL THIS WHEN'), and value proposition ('WHY'). Every sentence serves a distinct purpose. No redundancy with structured fields (title/annotations). Appropriate length for complexity.

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 feedback utility with no parameters and no output schema, the description is complete. It covers invocation triggers, expected content, and value proposition. No gaps exist given the tool's simplicity; the agent understands exactly when and why to invoke this tool.

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 0 parameters, setting baseline 4 per evaluation rules. The description mentions including specific content ('dead_code_report') which contextualizes how to use the parameterless tool, though without explicit parameters in the schema, no additional semantic mapping is required or provided.

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 defines the tool's purpose using specific verbs ('Call this', 'Submit') and identifies the resource (feedback). It distinguishes itself from siblings by referencing specific tools like 'get_unused_code' and scenarios like 'A search returned no results' that map to other tools in the server (search_functions), effectively differentiating when to use feedback versus direct tool invocation.

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?

Excellent explicit guidance via 'CALL THIS WHEN:' bullet points covering empty results, missing information, positive reinforcement, workarounds, and specific false positives from get_unused_code. It provides concrete trigger conditions and even specifies what content to include ('include dead_code_report'), giving clear alternatives to using other tools.

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

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

Annotations indicate read-only safety; description adds valuable behavioral constraints including 'All sub-queries run in parallel server-side' and explicit 'LIMITS' section (max 5 modules, 3 searches, etc.). Does not disclose latency, caching, or permission requirements.

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?

Excellent structure with clear semantic headings (CALL THIS WHEN, RETURNS, LIMITS). No wasted words; every sentence provides specific guidance on capabilities, constraints, or alternatives.

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 no output schema, description comprehensively details return value ('codebase map, module profiles, search results...'), aggregation behavior, and operational limits. Complete for a zero-parameter reconnaissance tool.

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?

Zero parameters present (baseline 4). Description appropriately omits parameter discussion since none exist, though it implies capability constraints (limits) that would typically be parameterized, potentially causing slight confusion.

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 clearly states the tool 'Get[s] the full architectural picture in ONE call' and explicitly distinguishes from siblings by listing what it combines (codebase map, module deep-dives, etc.) and stating 'Use individual tools (get_module_context, get_blast_radius, search_functions, etc.) for follow-up deep-dives'.

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?

Contains explicit 'CALL THIS WHEN' section with three specific scenarios (starting tasks, reviews, when targets are known upfront) and directly names alternative individual tools for follow-up actions, providing clear when-to-use vs when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true. Description adds graph traversal behavior (reveals 'transitive paths', 'indirect connections', 'full module graph'), return value structure ('Forward and reverse dependency paths', 'circular dependency detection', 'shared dependencies'), and safety context (analysis operation with warnings). Does not mention rate limits or performance constraints.

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?

Well-structured with clear headers (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES). Front-loaded with core purpose in first sentence. Slightly verbose but every section adds distinct value; examples are concrete and help clarify intent.

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?

No output schema exists, so description adequately explains return values (dependency paths, circular detection, shared dependencies). Covers purpose, usage contexts, return format, and differentiators from siblings. Absence of parameter documentation is appropriate given 0-param schema.

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 contains 0 parameters. Per rubric, 0 params = baseline 4. Description conceptually references 'two modules' but does not contradict the schema (no parameter section claimed); this describes the conceptual scope of the analysis rather than specific input fields.

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?

Opening sentence uses specific action verb 'Trace' with clear resource 'modules' and scope 'how two modules are connected'. Distinguishes from file-reading and general mapping tools via 'BEFORE splitting, merging, or decoupling' qualifier and the 'WHY NOT JUST READ FILES' section explaining transitive graph analysis vs direct imports.

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?

Contains explicit 'CALL THIS WHEN:' section with 4 specific refactoring scenarios (circular dependencies, extraction planning, change impact analysis). Includes 'WHY NOT JUST READ FILES' section that explicitly contrasts with manual inspection alternative, explaining transitive paths vs direct imports.

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

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

Superb. Annotations only state readOnlyHint=false/destructiveHint=false. Description adds critical operational context: single-use URL with 10-minute expiration, exact data transmitted (structural metadata only), agent execution responsibilities ('execute this bash block directly'), and requires user approval. Privacy disclosure ('Source code never leaves') 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?

Excellent structure with three distinct sections: purpose/privacy guarantee, usage conditions with bullet points, and execution instructions. Front-loaded with clear verb. No redundant text; complex operational details (expiration, single-use, local parsing) are essential.

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?

Thorough despite no output schema. Description compensates by detailing return value format ('ready-to-run bash block'), side effects (repo mapping), authentication needs (user approval), temporal constraints (10-minute expiry), and data handling policies. Covers all operational gaps.

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?

Baseline 4 for 0 parameters. Input schema is empty object. Description mentions 'When path is provided' which appears to reference a parameter not defined in schema, potentially causing confusion, but with zero parameters there is no schema documentation to supplement.

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?

Excellent. States specific action ('Map a local repo into Pharaoh'), identifies the resource (local repo), and distinguishes from sibling workflow ('without installing the GitHub App'). The privacy guarantee ('Source code never leaves the machine') further clarifies the scope.

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?

Exceptional. Explicit 'CALL THIS WHEN:' section with four specific bullet points includes trigger phrases ('analyze this repo'), references sibling tool get_codebase_map for conditional logic, and identifies target scenarios (private repos without admin access). Clear differentiation from GitHub App installation path.

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

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

With readOnlyHint:true already indicating safe read operations, the description adds valuable return value disclosure: 'Matching functions with file paths, line numbers, module, export status, async flag, complexity scores, and full signatures.' It also clarifies scope: 'Searches all functions across the entire codebase' and 'full resolved dependency graph.' Could mention performance characteristics or caching behavior for a perfect 5.

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?

Well-structured with clear headers (CALL THIS WHEN, RETURNS, EXAMPLES, WHY NOT JUST READ FILES) making it scannable despite length. Every section earns its place—examples are concrete, justification vs grep is distinctive context. Slight deduction only because the length is substantial for an MCP description, though justified by the zero-parameter nature requiring clear usage guidance.

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 no output schema exists, the description comprehensively documents return values (file paths, line numbers, signatures, etc.). For a zero-parameter, read-only search tool, it adequately covers scope (entire codebase), behavior (dependency graph resolution), and use cases. No gaps identified given the tool's simplicity and annotation coverage.

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 0 parameters (empty object), triggering the baseline score of 4 per rubric ('0 params = baseline 4'). Description appropriately does not invent parameter documentation where none exist, and the provided examples demonstrate usage patterns without implying non-existent 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?

Excellent specificity: 'Check if functionality already exists BEFORE writing any new function' provides clear verb (search/check) and resource (functions). It distinguishes itself from siblings like get_codebase_map (structural overview) and query_dependencies (dependency graph) by focusing specifically on finding existing implementations to prevent duplicate code.

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?

Explicit 'CALL THIS WHEN:' section lists 4 specific trigger conditions (before creating functions, finding implementations, importing vs reimplementing, verifying existing functionality). It also includes 'WHY NOT JUST READ FILES' contrasting against grep alternatives, providing clear guidance on when to prefer this tool over simple file reading.

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

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

Annotations indicate read-only/destructive hints, but description adds critical behavioral context: explains return format ('curated list...with install commands'), scope ('tailored to the languages'), and persistence model ('one-time setup...persist across sessions'). Clarifies that tool returns commands rather than executing installation.

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?

Well-structured with clear sections: purpose statement, trigger conditions, return value documentation, and persistence note. Front-loaded with the core action. Slightly verbose but each sentence earns its place by specifying triggers or persistence behavior.

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?

No output schema exists, but description compensates by detailing what gets returned (plugin list with install commands) and execution model (user runs commands). Adequately complete for a zero-parameter setup tool.

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?

Zero parameters present, which per guidance warrants a baseline score of 4. No penalty applies since there are no parameters requiring semantic clarification beyond the empty schema.

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 opens with specific verb ('Set up') + resource ('Claude Code environment') + specific deliverable ('Pharaoh's curated plugin bundle'). Clearly distinguishes from sibling tools which are all analysis/read-only tools (get_codebase_map, check_reachability, etc.) rather than setup/configuration tools.

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?

Contains explicit 'CALL THIS WHEN:' section with three specific trigger conditions, including exact user phrases to listen for ('set up my environment', 'install plugins') and proactive conditions (after noticing LSP needs). Provides concrete usage guidance without needing alternatives.

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