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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behaviors: in-memory compilation with caching, that parse/type errors are returned as results rather than isError, stable error codes for failures, and that it writes/executes nothing. This is far richer than the annotation hints alone.

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 long but every sentence earns its place—purpose, usage, return shape, and error handling are densely packed without fluff. It is front-loaded with the core purpose and usage, making it easy to scan.

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?

It covers purpose, usage, behavioral details, return shape (ok, diagnostics with fields), and error handling (stable codes, isError behavior). Given the output schema exists, the description fully equips an agent to call the tool correctly and interpret results.

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% with a clear description, but the description adds meaning: the file is compiled with every sibling in its directory, so imported names resolve, and answers may name sibling files. This contextual detail helps the agent understand the parameter's role beyond a simple path.

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 states a specific verb ('check') and resource ('.hird file's whole program'), and explicitly distinguishes itself from siblings: 'nothing else reports a warning, and the other tools fail on the first error instead of listing them all.' This makes its purpose unmistakable and differentiates it clearly.

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?

Explicitly prescribes when to use it: 'Use it as the first and last step of an edit' and explains why (other tools fail early, nothing else reports warnings). It also implies exclusions by noting other tools' behavior, giving clear context for choosing this tool over 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses in-memory compilation with caching, no writes or execution, whole-program reach, module-qualified name resolution, and stable error.code values with diagnostic shapes. Nothing is hidden and nothing contradicts 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?

The definition is front-loaded with the action and scope, and each block (use case, alternatives, reach, output shape, safety, errors) earns its place. It is longer than typical descriptions, but justified by the tool's cross-module semantics and error-handling complexity; a slight trim of the output-shape and error enumeration would improve it.

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 complex graph tool with only two parameters, the description covers invocation trigger, output shape, cross-module behavior, read-only guarantees, and error modes. An agent has enough context to decide when to call it, invoke it correctly, and interpret failures.

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 already covers both parameters at 100%, including path resolution and actor qualification rules, so the baseline is 3. The description reinforces the meaning of the root/module and failure behavior but does not materially add new parameter-level semantics beyond 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 first sentence names a specific verb/resource ('Emit the actor/effect graph rooted at one actor') and specifies exactly what nodes are included: reachable actors, supervisors with children, and tools. It also distinguishes itself from explain_actor_protocol and get_context_budget by naming alternatives, so an agent can tell the tools apart.

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 trigger: use it for 'what does this actor transitively do or depend on' and explains why (per-process effect rows hide transitive reach). It also tells the agent to use explain_actor_protocol for a single actor's interface and get_context_budget to gauge size before requesting it. This is clear routing among 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?

The description goes beyond annotations (which only state read-only, idempotent, non-destructive) to disclose that the tool compiles the file's directory in memory with caching, writes/executes nothing, and returns failures with stable error codes. It also details the error code taxonomy and the shape of diagnostics. This is rich additional behavioral context. It does not contradict annotations, and it adds value by specifying the compilation behavior and error handling.

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 substantial but well-structured: it starts with the primary purpose and immediate alternatives, then provides return structure, parameter resolution, and error behavior. It earns its length by packing essential information. It is not excessively verbose; each sentence contributes to understanding. However, it could be slightly more front-loaded by placing the alternatives earlier, but the current order is logical.

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 complexity (rich output structure, error handling, parameter resolution rules), the description covers everything an agent needs: return shape, resolution semantics, error codes, and side-effect-free behavior. The output schema exists, but the description still explains the meaning of the fields and the error data, making it complete for correct invocation and interpretation.

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. The description adds meaning by explaining how `actor_name` resolves (local, imported, qualified) and the effect of `file` (compiling the whole directory). It also details the return structure including the `display` string for types and rows, and failure conditions. This goes beyond a simple restatement of parameter definitions, but since the schema already describes each parameter thoroughly, the additional value is moderate.

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's purpose: to describe an actor's protocol, enumerating the specific components (message type, state type, init effects, per-handler effects, effect summary). It uses a specific verb ('Describe') and resource ('actor's protocol'), and distinguishes itself from siblings like 'emit_actor_effect_graph' and 'lookup_definition' by naming them and stating their alternative purposes.

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 explicitly says when to use this tool: 'Use it to learn how to talk to an actor or what each handler may do'. It also gives clear alternatives: 'use `emit_actor_effect_graph` for transitive actors/supervisors/tools' and 'use `lookup_definition` if you only need its location'. This provides both when-to-use and 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, destructiveHint=false, idempotentHint=true. The description complements these with specific context: it compiles the file's directory in memory with a cache until a sibling changes, and writes or executes nothing. It also details failure modes, including stable error.codes and the consistent shape of error.data.diagnostics. This goes beyond the annotations and gives the agent an accurate model of what the tool does under the hood.

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 dense and information-rich, but it is also lengthy and slightly run-on. It front-loads the core purpose and usage, then flows into behavioral details and error codes. Although every sentence adds value, the structure could be improved with clearer separation (e.g., bullets) to reduce cognitive load. It remains within acceptable bounds for a complex tool.

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?

The description is exhaustive for its complexity. It covers the return value structure (name, type, effect_row, open, pure, effects), the edge cases (not_a_function, not_found), and all possible error codes with their data shape. Combined with the rich output schema and the annotations covering resource safety, an agent has everything needed to call the tool correctly and interpret results. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. Still, the description adds meaning: it clarifies that `file` can be relative to the server's working directory and that sibling files are compiled together, so names may resolve to other files. For `fn_name`, it specifies the syntax for imports and qualifiers, which is not in the schema. Despite high coverage, this added context justifies a score above baseline 3.

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 precise verb–object pair ('Explain a function's effect row') and immediately defines what it covers: the canonical row plus a one-sentence explanation of each effect. It clearly identifies the target resource (a single named function) and differentiates itself from siblings by naming alternatives (infer_type, emit_actor_effect_graph). It also specifies edge cases (not_a_function, not_found), leaving no ambiguity about what the tool does.

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 gives explicit guidance on when to use this tool: for 'what may this function do' or interpreting unfamiliar effects. It explicitly names alternatives and the conditions that select them: use infer_type for an arbitrary expression's row, and emit_actor_effect_graph for an actor's transitive effects. This actionable routing leaves no inference to the agent.

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 goes well beyond the annotations. It discloses that the tool is read-only (compiles in memory, cached until a sibling changes, writes/executes nothing), which reinforces the readOnlyHint. It also discloses failure modes with stable error codes (file_not_found, read_error, invalid_params, parse_error, check_error) and the shape of diagnostics. It even explains the estimation heuristic (~4 characters per token from one-line signatures). This is rich behavioral context that annotations alone do not provide.

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 dense but well-organized: purpose first, then usage, then return shape, then failure modes. Every sentence carries information. It is longer than the typical description, but the length is justified by the behavioral and error details. It loses one point because the failure-mode enumeration is somewhat verbose and could be tightened without losing meaning.

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?

The description is complete for a read-only estimation tool. It covers what the tool returns (approx_tokens with per-category breakdown and total), the estimation method, the failure modes with error codes, and the read-only safety profile. The output schema exists, so return values are further documented. An agent has everything needed to decide when to call it and how to interpret results.

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 schema already provides 100% coverage of the single parameter, including path resolution semantics and the fact that sibling files are compiled together. The description adds value by explaining why that matters ('so imported names resolve; answers may name a sibling file') and by clarifying the tool's scope ('it names no individual symbols'). Since the schema covers the parameter well, the description's additional context earns a 4 rather than a 3.

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 states a specific verb ('Estimate'), a specific resource ('token cost of loading a file's declarations'), and enumerates the exact categories counted (types, effects, actors, supervisors, tools, function signatures). It also explicitly distinguishes itself from siblings by noting it 'names no individual symbols' and by referencing get_context_for_symbol as the alternative for symbol-level queries. This is a clear, differentiated purpose.

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 gives explicit when-to-use guidance: 'Use it before pulling a module in wholesale, to choose between get_context_for_symbol calls and a full read, or to pick a budget.' It also names the alternative tool (get_context_for_symbol) and the decision it informs. This is exactly the kind of routing guidance an agent needs.

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, idempotentHint=true, destructiveHint=false, and the description reinforces this by stating it writes/executes nothing and only compiles in memory (cached). It also discloses failure behavior, error codes, and the not_found shape, which goes beyond annotations and gives the agent actionable detail.

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 dense but front-loaded with the main purpose and usage; all sentences earn their place. It is somewhat long, but it packs a lot of necessary operational detail into a compact structure, so it earns a 4 rather than a 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?

Given the tool's complexity, the rich annotations, and the presence of an output schema, the description is complete: it covers purpose, ordering semantics, omissions, failure codes, and read-only behavior. It also references sibling tools sufficiently. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are fully described in the schema. The description adds a bit of context about token estimation and omission behavior but does not need to compensate for missing schema docs. Baseline 3 is appropriate.

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 clear verb ('Summarize') and resource ('one symbol'), and specifies the target use ('for an LLM prompt within an approximate token budget'). It explicitly distinguishes itself from siblings like lookup_definition, explain_effect_row, and render_ir_fragment, and describes return fields. The title also reinforces the intent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides direct guidance: 'Use it as the default way to bring a symbol into context' and explicitly lists alternatives for other needs (lookup_definition for location, explain_effect_row for effect explanations, render_ir_fragment for full body). This is ideal routing information.

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 the readOnlyHint and idempotentHint annotations, the description discloses that the tool compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. It also details error handling, including stable error codes and the shape of diagnostics. These behavioral details go beyond annotations and are valuable for the agent.

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 dense but well-structured, front-loading the main purpose and providing usage guidance early. Every sentence adds value, covering purpose, alternatives, return values, error cases, and side-effects, all in a compact paragraph without redundancy.

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 moderate complexity with three parameters and an output schema, the description covers all necessary aspects: what it returns, side effects, error handling, and read-only nature. The output schema likely explains return types, so the description need not repeat them. This is complete for an agent to call 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?

The schema already provides descriptions for all three parameters, so schema description coverage is 100%. The description adds context by explaining that line and column are 1-based, and that column is character-based (not byte), plus that any position in the token works. However, this is marginal; the schema already covers the core 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?

The description clearly states the tool's purpose with a specific verb ('Infer') and resource ('type and effect row of the expression at a source location'). It explicitly names sibling tools for alternatives, such as `lookup_definition` for named top-level definitions and `explain_effect_row` for effects with explanations, which distinguishes it from potentially confusing peers.

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 provides explicit guidance on when to use this tool: for 'what is the type here' on local bindings, sub-expressions, and names in `use` lists. It also provides clear alternatives and when to prefer them: `lookup_definition` for named top-level definitions and `explain_effect_row` for function effects with explanations. This fully covers usage 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?

The annotations already declare readOnly, idempotent, and non-destructive. The description goes beyond that by disclosing that the tool compiles the file's directory in memory (cached until a sibling changes) and runs no side effects, and by giving a full list of stable error codes and diagnostic shapes. No contradiction exists; the description adds valuable behavioral context the annotations do not cover.

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 longer than average, but every sentence carries a distinct fact: purpose, use case, return structure, behavior, and error handling. It is front-loaded with the core purpose and usage guidance before diving into output details, with no filler or tautology.

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 is a small, read-only helper, the description is complete. It explains the return shape, the semantics of each field, the caching behavior, and all possible error codes. An agent has all the information needed to invoke the tool correctly and interpret its results.

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 fully covers the sole `file` parameter (path resolution, relative/absolute, compilation of a directory, import resolution). The description adds the caching detail and reinforces the read-only nature, but it does not fundamentally alter the parameter's meaning. With 100% schema coverage, the baseline is 3; the cache and error behavior are a small yet useful bonus.

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 begins with a specific verb and resource: 'Outline a .hird module: every name its top-level declarations bind, in source order, plus its imports.' It explicitly distinguishes itself from siblings by stating it is 'the only tool that names a module's symbols without a failed lookup' and referencing `get_context_for_symbol` as the follow-up, making it impossible to confuse with other 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?

It provides explicit guidance: 'Use it to orient in a module before choosing which symbols to pull in with get_context_for_symbol' and gives a clear contrast with alternatives (it is cheap because it has no bodies or effect graph, and it avoids failed lookups). This tells the agent exactly when to use it, when not to, and which alternative to select.

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 annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context beyond that: it compiles the file's directory in memory, is cached until a sibling changes, writes or executes nothing, returns not_found for unknown names, and exposes stable error codes. This exceeds the coverage provided by annotations alone.

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 long but every sentence earns its place: purpose first, then sibling routing, then return shape, unknown-name behavior, read-only guarantee, and error code taxonomy. It is dense, well-ordered, and free of 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?

Given the tool's complexity, the output schema, and the annotation context, the description is complete: it covers return values, naming semantics, imported-name behavior, failure modes, caching, and relationships to sibling tools. An agent has all the information needed 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%, and the input schema's parameter descriptions are already rich, so the description does not need to add much. It contributes some framing by noting the lookup is by name and clarifying that the name is written as the source would write it, but the schema carries the main 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?

The description states a specific verb-resource pair ('Look up a top-level definition by name') and enumerates exactly what the tool returns: defining file/line, kind, type, and doc comment. It further distinguishes itself from siblings such as get_context_for_symbol and render_ir_fragment, so an agent can select it without ambiguity.

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 explicitly says to use this tool first to locate or identify a symbol and names the alternatives for additional needs: get_context_for_symbol for effects/callers/callees, explain_effect_row for behavior, and render_ir_fragment for the body. This gives clear when-to-use and 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 already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: 'Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing.' It also details error codes, error.data shapes, and the stable error.code list, all beyond the annotations. No contradiction exists.

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 long, every sentence carries new information: purpose, use case, alternative tools, output fields, error scenarios, read-only behavior, caching, and error codes. It is front-loaded with purpose and usage, then moves to outputs and failures. Nothing is redundant.

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 tool with a rich behavioral and error profile, the description covers when to use, what to expect, error shapes, side-effect guarantees, and alternatives. An output schema exists, so the return type doesn't need full elaboration here. The description is complete for an agent 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 description coverage is 100%, so each parameter has a clear description. The tool description does not add parameter-specific meaning beyond what the schema provides; it only references output and error behavior. With full schema coverage, a baseline of 3 is appropriate.

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 precise verb-resource pair: 'Render the typed intermediate representation (IR) of one top-level definition as JSON.' It immediately distinguishes itself from human-oriented siblings by naming `get_context_for_symbol` and `lookup_definition` as preferred for human views, so an agent can tell exactly what this tool is for and what it is not.

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 explicitly states when to use it: 'Use it when the exact lowered structure matters: desugared bodies, the resolved type on every node, a tool's generated function.' It also gives an explicit exclusion: 'for a human-oriented view prefer `get_context_for_symbol` or `lookup_definition`.' This is textbook usage guidance with alternatives and conditions.

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