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

With no annotations provided, the description carries the burden of explaining behavior. It does disclose that scanner warnings are returned separately when present, which is useful, and explains the computed condition logic. However, it does not state side-effect profile, return format, or error 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?

A single sentence that front-loads the core purpose and then expands with the key condition details. It is compact and readable, though slightly dense with the colon-separated elaboration.

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 single parameter and relatively simple conceptual scope, the description is mostly adequate. It conveys what is being computed and even notes the separate scanner warnings. However, with no output schema, it does not specify the exact shape of the returned locations or conditions, leaving some ambiguity for an agent.

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 parameter already includes a descriptive example ('aqu_d%rchrg'). The description reinforces that the variable is the focus of the analysis but adds no new semantic detail 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 description clearly states the tool's purpose: finding where to stop to watch a variable and under what condition, including routines that assign it and the loops enclosing those assignments. It is specific about the resource (variable) and the kind of result, though it reads more like an output description than an imperative verb+resource statement.

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?

No explicit guidance is given about when to use this tool versus alternatives like writers, loops, provenance, or scope_at. The context is implied by the description, but there are no stated exclusions or comparisons to sibling 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?

With no annotations, the description carries the behavioral disclosure burden. It meaningfully adds that the result is 'Exhaustive, not truncated,' which is a valuable guarantee about completeness. It does not detail output format or error behavior, but the core behavioral trait is provided.

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 extremely concise and front-loaded. Every phrase earns its place: the purpose is stated first, and the completeness guarantee is added in the second clause with no wasted words.

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 simple single-parameter tool with no output schema, the description covers the essential semantics: what is returned and a completeness guarantee. It could specify whether the result is a list of names or objects, but the core behavior is sufficiently clear 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?

Schema description coverage is 100%, so the single 'procedure' parameter is already documented as 'Procedure name.' The tool description adds no further semantic detail about the parameter beyond what the schema provides, so the baseline score 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 clearly states that this tool returns the routines called by a given procedure. It unambiguously identifies the resource and the relationship direction, distinguishing it from the sibling tool 'callers' which covers the reverse direction.

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?

Usage context is implied: an agent should use this when it needs to know what a procedure calls. However, it does not explicitly mention when to prefer this tool over alternatives like 'callers' or 'call_path', so the agent must infer selection from the sibling list.

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 no annotations provided, the description carries the full burden, and it delivers key behavioral guarantees: results are exhaustive, never sampled, never truncated, and each result maps to exactly one caller. This adds meaningful, non-obvious context beyond the input schema, though it does not describe output format or error 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?

The description is a single, front-loaded sentence that immediately states the tool's purpose, then adds a crucial behavioral guarantee. Every word earns its place, and there is no redundant fluff.

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 simple single-parameter query tool, the description sufficiently explains the tool's behavior and result semantics without needing an output schema. It could go further by describing the result format or handling of unknown procedures, but the core information needed to call it correctly is present.

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 has 100% coverage for the single parameter, 'procedure', described as 'Procedure name'. The description adds no additional parameter-level detail, which is acceptable given the minimal parameter surface.

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 that this tool returns routines that call the specified procedure, and the explicit 'never sampled or truncated' guarantee distinguishes it from possibly partial or sampled alternatives. The focus on 'callers' is unambiguous and naturally separates it from the sibling 'callees' tool.

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 conveys when to use the tool: when an exhaustive, complete list of callers is needed. It clearly implies this is the authoritative source for caller information, but it does not explicitly name alternatives or state when not to use it.

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 phrase 'from an entry point down' discloses a directional traversal behavior, which is useful. However, with no annotations provided, the description carries the full burden and does not state output format, ordering, error behavior, or whether the result is a single path or multiple paths.

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 a single sentence with no filler or redundancy. It front-loads the core idea and is appropriately sized for a tool with one parameter.

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 there is no output schema, no annotations, and closely related sibling tools, the description is too sparse for an agent to confidently invoke the tool correctly. It does not explain what the returned data looks like, how it relates to callers/callees, or when this tool should be preferred.

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 procedure parameter is already documented with an example. The tool description adds little beyond the schema, but it does frame the parameter in the context of an entry-point-to-procedure path, which is a mild semantic contribution.

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 conveys that the tool traces how execution reaches a procedure via an entry point, which is a recognizable purpose. However, it lacks a concrete verb such as 'list' or 'return', and it does not explicitly differentiate itself from sibling tools like callers, callees, or provenance.

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 no guidance on when to use call_path versus the closely related sibling tools. It does not mention alternatives, exclusions, or use-case context, leaving the agent to infer the tool's niche from its name and vague purpose.

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 no annotations, the description carries the behavioral disclosure burden. It does disclose the output substance—all fields with units and meaning—which implies a read-only introspection operation. It does not mention error behavior, naming requirements, or whether inherited/nested fields are included, but the core behavior is reasonably conveyed.

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 a single compact sentence with no filler. The first clause states the core value, and the dash clause provides a concrete example. Slightly redundant, but efficient and well-sized for a one-parameter 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?

With no output schema, the description compensates by saying what is returned: all fields, with units and meaning. However, it does not describe the return structure, ordering, or any limitations, and the lack of an explicit verb leaves some ambiguity. It is adequate for a simple tool but not fully specified.

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% for the single 'name' parameter, so the description is not required to document it in depth. The phrase 'derived type' and the aqu_d example add domain context for what kind of type name is expected, but this is marginal beyond the schema's 'Type name, e.g. aquifer_dynamic'.

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 indicates the tool enumerates every field of a derived type, including units and meaning, and grounds it with a concrete example (aqu_d). The verb is implicit but recoverable from the tool name and phrasing. It does not explicitly name sibling tools, but the resource and output are specific enough to distinguish it from procedure-, I/O-, and scope-oriented siblings.

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 implies when to use it: when you need to know what fields and units a state object/derived type contains. It does not explicitly contrast against alternatives like search_fields or scope_at, nor state when not to use it, so the guidance 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?

With no annotations provided, the description carries the behavioral disclosure burden. It adds valuable traits: it is exhaustive over the whole tree, not truncated, and it resolves output files opened via open_output_file. This gives an agent meaningful expectations about scope and alias handling, though it does not explicitly state that the operation is read-only.

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 two sentences with no wasted words. It front-loads the core purpose and then adds two crucial refinements—open_output_file resolution and exhaustive coverage—each earning its place.

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 single-parameter query tool with no output schema, the description conveys what is returned (routines with unit numbers and lines) and key edge behaviors. It is sufficiently complete for an agent to select and invoke the tool correctly, though it could briefly mention the result format or whether output is sorted.

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 documents the single 'file' parameter with a descriptive example, giving 100% coverage. The description adds no new parameter-level information, which is acceptable because the schema fully defines the required input.

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 identifies routines that open/read/write a file, including unit numbers and lines. It distinguishes itself from siblings by focusing specifically on file I/O operations and by resolving files opened via open_output_file, though it lacks an explicit imperative verb like 'list' or 'find'.

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 implies when to use the tool: when you need to know which routines touch a given file, or when output files are opened through open_output_file. It does not explicitly compare against sibling tools like writers, unit_users, or read_output, nor does it state when not to use it.

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 no annotations provided, the description carries the transparency burden. It explicitly discloses that all stored fields are returned, never sampled or truncated, and that scanner warnings appear in a second content block and are advisory rather than compiler errors. This gives useful behavioral expectations beyond the 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 description is compact and front-loaded with the action word 'Locate'. The first sentence packs in many field groups without filler, though the phrase 'module imports and only lists' reads awkwardly and slightly obscures 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?

For a one-parameter tool with no output schema, the description covers the returned field groups, warns about sampling/truncation behavior, and explains the second content block. It does not mention not-found behavior or exact-match semantics, but these are minor gaps for this kind of lookup 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 schema already documents the single parameter with 100% coverage and provides an example value. The description adds no additional meaning about the name parameter beyond what the schema supplies, so the baseline score 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 states a specific verb and resource: locating a SWAT+ procedure, and enumerates the returned facts (source file, line range, module, imports, arguments, locals, case vocabularies). This makes the tool's scope clear, but it does not explicitly differentiate it from sibling tools like search_fields or describe_type.

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 implies use when a procedure's stored details are needed and mentions when warnings are returned. However, it gives no explicit guidance about when to prefer find_procedure over related sibling tools, so routing 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?

With no annotations provided, the description carries the behavioral disclosure burden and does well. It explicitly states the results are exhaustive (every loop, not a sample) and that scanner warnings are returned separately. This gives useful behavioral expectations beyond a simple 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?

The description is compact, front-loaded with the key purpose, and every sentence adds value. It avoids padding while still conveying scope, output contents, exhaustiveness, and the handling of warnings.

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 tool is simple (one parameter, no output schema), and the description covers what the tool returns, its purpose, its exhaustive scope, and the separate handling of warnings. An agent has enough context to select and 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 the schema already documents the only parameter, 'procedure'. The description does not add extra meaning about the parameter, but the schema plus the tool's focus are sufficient for an agent to understand what to supply.

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 resource (loop headers in a procedure), what it returns (index variables, start/end lines), and its purpose (setting a conditional breakpoint). It is distinguishable from siblings like breakpoint and find_procedure, though it uses a noun phrase rather than an explicit verb like 'return' or 'list'.

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 clear context: use this tool when you need loop header information for setting a conditional breakpoint. It does not explicitly name alternatives or state when not to use it, but the breakpoint-focused purpose is strong 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?

With no annotations, the description carries the full burden. It does disclose what information is returned, which helps set expectations, but it does not explicitly state whether the tool is read-only or whether checking compile status triggers any build/scan side effects.

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?

A single compact sentence with no filler. It front-loads the purpose and lists the output fields efficiently.

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 and no output schema—the description covers the main return pieces well. It could be slightly more complete by clarifying what 'index' refers to and whether any action is performed, but overall it is sufficient for basic selection and 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?

The tool has zero parameters, so the baseline is 4. The description adds useful context by indicating that the tool operates on 'this index', even though no parameters are declared.

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 identifies a specific resource—provenance info for the current index—and names the exact pieces of information returned: SWAT+ checkout, commit, compile-check status, and scanner-warning count. It is distinct from the sibling code-analysis tools, though it lacks an explicit verb like 'returns' or 'reports'.

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?

There is no guidance on when to use this tool versus any alternative, and no mention of prerequisites or context. The description implies a query about the current index but does not explain when this is the right choice among the listed 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?

With no annotations, the description carries the disclosure burden and it explains the non-obvious behavior: it returns aggregate stats (count, first, last, min/max with locations, negative count) rather than raw output. However, it does not comment on error conditions, exact return formatting, or how optional filters interact with the summary.

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?

One tightly worded sentence front-loads the action and target, then lists the concrete statistics in a compact enumeration. There is no filler or repeated schema content.

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 read-only summarizer with full schema parameter documentation, the description covers what the output contains, which compensates for the absence of an output schema. Minor gaps remain (error behavior, exact result shape) but they are not essential for selecting and invoking the 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?

Schema description coverage is 100%, so the schema already explains file, column, where, and label_by. The description adds a little semantic color by explaining that min/max locations are reported, which maps to label_by, but it does not meaningfully enrich the other 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?

The description names a specific verb ('Summarise'), a specific resource ('a column of a run's output file'), and enumerates the exact computed statistics. This clearly distinguishes read_output from the code-analysis sibling tools, none of which perform output-file summarization.

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?

No explicit when-to-use/when-not-to-use guidance is provided, and no alternative tools are named. The only usage context must be inferred from the purpose statement itself, which carries no exclusions or choice 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?

Since no annotations are provided, the description carries the behavioral disclosure burden. It does a good job by stating the output ordering ('outermost first') and that scanner warnings are returned separately. It does not mention error behavior for invalid lines/procedures, but the disclosed ordering and separate warning channel add real transparency.

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 two compact sentences with no fluff. The first sentence leads with the core query and ordering; the second adds relevant behavior about warnings. Every clause earns its place.

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 low-complexity lookup with two simple, fully described parameters and no output schema, this is largely complete: it tells the agent what it returns, in what order, and that warnings come separately. It could be more explicit about not-found cases or the exact shape of returned loop identifiers, but the current description is sufficient for most selection and invocation decisions.

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 as 'Procedure name' and 'Line number'. The description restates them conceptually ('given line of a procedure') but adds no format constraints, examples, or value ranges. 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?

The description clearly states the tool's purpose: returning the loops that enclose a given line of a procedure, ordered outermost first. The phrase 'the variables live at that point' adds useful semantic context. It does not explicitly contrast with the sibling tool 'loops', but the line-specific focus is distinctive enough.

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 implies when to use it: when you need loop nesting or variable scope at a specific line in a procedure. There is no explicit guidance on when not to use it or how it differs from the sibling 'loops' or 'provenance' tools, so the guidance is only implied rather than explicit.

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 no annotations, the description carries the full burden of behavioral disclosure. It reveals that the search is semantic, not exact-name-based, and that results include identifiers with units. However, it does not mention matching behavior, case sensitivity, failure modes, or whether results are limited in any way, leaving meaningful gaps.

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 two sentences with no filler. The primary purpose is front-loaded, and the example immediately grounds the usage. Every sentence contributes 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?

This is a simple one-parameter search tool with no output schema, and the description covers what it searches, how it searches, and what it returns. It stops short of describing the exact return structure, but for a query-by-text tool this is sufficient for an agent to invoke it correctly in most cases.

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 modest value by reinforcing that 'text' should be ordinary words or phrases and providing concrete examples. This clarifies the expected input format beyond the schema's minimal description.

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 action ('Find a variable from ordinary words') and a distinctive method: searching what the source says each field means. It also mentions the return value ('identifiers with units'), which helps an agent understand what the tool produces. It does not explicitly contrast with siblings like find_procedure, but the resource and search semantics are clear enough to differentiate.

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 implies usage: call this when you have ordinary-language words describing a field's meaning, illustrated with 'recharge' or 'lateral flow'. It provides no explicit when-not-to-use guidance or alternatives, leaving the agent to infer distinctions from sibling names.

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 no annotations, the description carries the burden. It usefully adds 'Exhaustive, not truncated' and describes the returned relationship (routine to targeted file), but it does not explicitly state read-only behavior, output shape, or any costs or limits. It is adequate but not richly transparent.

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?

Three short clauses, no filler, and the key constraint 'Exhaustive, not truncated' is included without extra words. Every sentence earns its place.

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 simple two-parameter lookup with no output schema, the description conveys what will be returned (routines and file targets) and the optional filter. It could be slightly fuller about what 'targets' means and any empty-result behavior, but it is close to complete.

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 structured fields already document unit and op; the description only restates that op is optional. No additional format, constraints, or edge-case meaning is provided 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 description identifies the resource (a Fortran unit number) and the result (routines using it and the file each targets), so the agent can infer this is a lookup tool. It lacks an explicit imperative verb like 'List' or 'Find', and it does not differentiate itself from sibling tools such as file_io.

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 phrasing 'Routines using a Fortran unit number' implies the tool is for unit-number-based lookup, and 'Optionally filter by operation' gives a usage tweak. It never states when to prefer this over file_io or related siblings, nor gives any exclusions.

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 no annotations provided, the description carries the full disclosure burden. It discloses exhaustiveness ('never sampled or truncated'), output content (line numbers and complete assignment statements), and that scanner warnings are returned separately. It does not explicitly state read-only behavior, but the operation is clearly a read-only lookup, and the sidecar caveat is a useful limitation disclosure.

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?

Three sentences each contribute meaningful information: purpose/output, exhaustiveness, and warning behavior. The core purpose is front-loaded. The first sentence is grammatically dense and includes the unexplained 'RHS sidecar' term, which prevents a perfect score.

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 simple one-parameter tool with no output schema, the description tells the agent what is returned, how complete it is, and what caveats exist. It does not explain what the RHS sidecar is or specify the exact return structure, but enough is present for correct invocation and basic result 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?

Schem description coverage is 100%, so the schema already documents the 'variable' parameter and its derived-type root usage. The description adds only a minor nuance about derived-type paths with the sidecar, which is more behavioral than parameter-semantic. 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 clearly states the tool's core function: finding routines that assign a given variable, with line numbers and logical assignment statements. It differentiates from read/call-oriented siblings like read_output and callers by focusing on write/assignment locations. The phrase 'when the RHS sidecar is installed' is an opaque qualifier that slightly clouds the main 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?

Usage guidance is implied: if you need to know where a variable is assigned, this is the tool. However, no explicit when-not-to-use instructions or alternatives are mentioned, leaving the agent to infer from sibling names. The exhaustiveness statement hints at use cases but does not formalize them.

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