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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the return payload shape (risk, production callers by module/file, endpoints, cron jobs, DB operations), the cost-limiting semantics of hops and the depth range, and the important exclusion of test-file callers. That is real behavioral context an agent cannot get from the 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?

Front-loaded with the core question, then clearly labeled CALL THIS WHEN, RETURNS, and USE INSTEAD OF sections. Each line carries distinct information, and the hop/exclusion caveats sit inside RETURNS where they belong.

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?

There is no output schema, and the description compensates by enumerating the returned fields, the depth semantics, and the test-file exclusion. For a 4-parameter read-only analysis tool, an agent has everything needed to call it correctly.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: hops are the 'shortest detected path' within the requested depth, and test-file callers are filtered out. It does not clarify the entity/entity_type pairing or the repo scoping beyond what the schema says.

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 line 'What breaks if you change a function, file or module' names the exact analysis performed and the entity types it accepts, so an agent can recognize impact analysis immediately. It does not explicitly distinguish itself from close siblings like get_module_context or search_functions, which keeps it short of a 5.

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?

A dedicated 'CALL THIS WHEN' block gives the triggering conditions (about to change a signature, refactor or delete; need callers or endpoints), and 'USE INSTEAD OF: following callers by hand' names the manual alternative it replaces. Nothing is left to inference.

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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the composition of the result set (flagged two-way dependencies, 90-day change frequency, endpoint-to-handler mapping), which tells the agent this is a single synthesized read rather than a raw listing.

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?

Front-loaded one-line summary, then labeled WHEN / RETURNS / USE INSTEAD OF sections with no filler. Every line carries actionable information and the structure lets an agent scan to the relevant part 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?

With no output schema, the description correctly carries the burden of describing returns and does so concretely. It leaves minor gaps around scale behavior (large repos, truncation) and the name-resolution path it advertises, but an agent has enough to invoke it correctly.

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 100%, so both parameters are already documented in the schema and the baseline of 3 applies. The description does not clarify how to resolve an unfamiliar 'repo' name despite flagging that case as a use reason, and never mentions include_metrics or what omitting it costs.

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 names a specific verb+resource ('a repo's architecture in one call') and enumerates the concrete content: modules with file counts/LOC, dependencies, hot files, endpoints with handlers. It differentiates from directory listings, but does not distinguish itself from siblings like get_module_context or get_blast_radius, which overlap on module-level questions.

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?

An explicit 'CALL THIS WHEN' block gives two clear triggering conditions (need overall structure / which module owns something; don't know the repo's exact name), which is strong positive guidance. It names a non-tool alternative ('directory listings') but gives no exclusions or pointers to the actual sibling tools an agent should weigh it against.

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 already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real value by quoting a cost budget (~2K tokens) and enumerating the exact payload (files, LOC, signatures with complexity, imports, DB tables, endpoints, crons, env vars, callers). It stops short of noting size limits on very large modules or whether output is truncated.

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?

Front-loaded with the one-line value proposition and a cost estimate, then sectioned into WHEN / RETURNS / INSTEAD OF. Every block earns its place and nothing is restated.

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 only two required params, no output schema, and no nested objects, the description covers everything an agent needs: trigger conditions, a token-cost expectation, and a full enumeration of the return contents. Nothing material is left to guesswork.

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 100% — both `repo` and `module` are documented in the schema, including an example value for module. The description adds no syntax, naming, or format guidance beyond that, so the baseline 3 applies.

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?

Names a specific resource (one module's full profile) and frames the intent around pre-change reconnaissance, which is distinct from `get_codebase_map` (whole repo) or `search_functions` (targeted lookup). However it never names a sibling tool, so an agent must infer whether `get_blast_radius` or `pharaoh_recon` overlaps. Clear purpose, but sibling differentiation is implicit rather than stated.

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' block gives two concrete triggering conditions (about to change a module; need exports/deps/callers) and 'USE INSTEAD OF' rules out reading files directly. What is missing is an explicit pointer to the actual sibling tools it supersedes or defers to — 'reading every module file' is a manual workflow, not a tool, so the routing decision against `get_blast_radius` remains unstated.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description goes further by defining the Dead/Possibly unused/Used only by tests categories and the caveat about string dispatch and dynamic loading, which materially affects how an agent should act on results. It does not, however, discuss scale or latency for large repos, and it partially duplicates the return-value content that would normally belong to an output schema.

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 purpose is front-loaded in the first sentence and the CALL THIS WHEN / RETURNS / USE INSTEAD OF sections make it scannable. It is slightly longer than strictly necessary, since the RETURNS section restates details that an output schema would normally carry, but nothing is filler.

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, the description does a good job of explaining the three result categories and the `functions`-mode response. What is missing for a repo-wide analysis tool is any sense of cost or latency on large codebases, and the `module` scoping parameter is never mentioned in prose, leaving a gap in an otherwise complete picture.

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 coverage is 100% (all three parameters are described in the schema), so the baseline is 3. The description adds meaning for `functions` by framing it as a targeted check that returns status plus a call path from an entry point, but `module` and `repo` are left entirely to the 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 opens with a specific verb and resource: find functions no production entry point (endpoint, CLI command, cron job, event handler, worker, entry file) reaches. It enumerates the exact classes of entry points that count, which lets an agent distinguish this from sibling tools like search_functions or get_codebase_map without opening a 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?

It gives an explicit CALL THIS WHEN section with two concrete triggers (before cleanup, after merging), plus a USE INSTEAD OF directive that names the alternative approach (reference searches) and the reason references are insufficient. When and why-not are both stated directly.

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=false and destructiveHint=false, and the description adds real behavioral context: invalid action/field combinations are rejected, and set_free_repo changes which repo is live while refresh_repo re-maps immediately. It doesn't note permission requirements or what happens to in-flight pushes during a refresh, so it stops short of the top.

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?

Front-loaded one-line summary, a compact per-action bullet list, a when-to-use block, and a flag glossary. Every section serves a distinct purpose with no filler.

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 three-action dispatcher with no output schema, the description covers what each action does, what status returns (plan, live repo, upgrade link, setup page), and the flag semantics. An agent has everything needed to pick an action and populate fields correctly.

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 coverage is 100% and the schema already tags each field with 'Used by: …' and the repo slug format. The description restates the per-action field mapping and the meaning of 'full' almost verbatim from the schema, so it adds little beyond the structured data.

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 names a specific resource domain (plan, live repo, refreshes) and enumerates each of the three actions with what it does: status reads plan/live repo, set_free_repo changes a free workspace's live repo, refresh_repo re-maps a repo. The sibling tools are all code-analysis utilities, so the account-management scope is unmistakably distinct.

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?

A dedicated 'CALL THIS WHEN' block lists four concrete triggering conditions, including the failure mode ('A repo doesn't answer because it isn't live') that selects set_free_repo. It also implies when to use refresh_repo versus status, leaving little to inference.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: queries execute in parallel, results come back as 'each requested section in one response,' and per-call caps are enumerated. It stops short of describing failure modes (e.g., what happens if one section errors) or payload size.

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?

Front-loaded one-sentence purpose, then clearly labeled CALL THIS WHEN / RETURNS / USE INSTEAD OF sections. Every sentence carries distinct information: what it does, when to fire it, what comes back, and what it replaces.

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 six-parameter batch tool with no output schema, the description is nearly sufficient: it explains that each requested section returns in one response and sets per-call limits. Some ambiguity remains about what a 'module profile' or 'codebase map' section actually contains, but annotations and full schema coverage fill most of the gap.

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 100%, so every parameter including the nested blast_radius and dependencies objects is already documented in the schema. The description's per-call caps ('up to 5 modules, 3 searches, 3 blast radius targets, 3 dependency pairs') echo the schema's max annotations rather than adding new semantics. Baseline 3 applies.

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 names a specific verb+resource (batched Pharaoh queries) and enumerates exactly which five query types it runs in parallel: codebase map, module profiles, function searches, blast radius, and dependency paths. An agent can distinguish it from every sibling (get_codebase_map, get_blast_radius, search_functions, etc.) without opening a 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?

'CALL THIS WHEN: Planning a change, reviewing a PR or assessing architecture, when you know what to check' gives explicit activation conditions, and 'USE INSTEAD OF: separate tool calls and file reads' names the alternatives it displaces. The qualifier 'when you know what to check' implicitly routes open-ended exploration elsewhere.

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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds value beyond that by disclosing the exact return payload fields (file path, line range, module, signature, export status, complexity). It does not mention pagination/limit behavior or ranking/relevance ordering, which is the remaining gap for a search 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?

Front-loaded one-line purpose followed by three short labeled blocks (when, returns, alternative). No filler sentences; every line adds decision-relevant 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 7 parameters, no output schema, and only read-only annotations, the description compensates well: it explains the return shape, the intent, and the alternative tool. Nothing an agent needs to select or invoke it correctly appears to be 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 100%, so every parameter (file, repo, limit, query, module, offset, exported_only) is already documented in structured form; the description only loosely implies 'name or concept' matching for query. Baseline 3 is appropriate since the schema carries the parameter burden.

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 and resource ('Find functions') with explicit scope ('by name or concept across the whole codebase'), and the returns line clarifies it's a semantic/keyword search rather than a structural map like get_codebase_map. An agent can distinguish it from grep and from the sibling recon tools without opening a 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?

The 'CALL THIS WHEN' block gives two concrete triggering scenarios (pre-writing a helper, locating an implementation) and names the concrete alternative to avoid ('USE INSTEAD OF: grep'), including the reason grep fails (misses aliases and re-exports, includes comments). That is explicit when/when-not guidance.

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