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

With no annotations, the description must disclose behavior; it does state 'read-only', which is a key safety trait. However, it doesn't describe what the output contains beyond the hints, or any prerequisites/errors. The output schema covers return format, but behavioral context like side-effect freedom is minimal.

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 concise sentence, front-loaded with the key phrase 'Read-only', and every word adds meaning. It doesn't waste space.

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 has no parameters and an output schema exists, the description provides the essential purpose and read-only guarantee. It could mention when to run it, but the scope is fairly obvious from the name and sibling context.

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

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

The tool has no parameters, so the description doesn't need to explain parameter details. It adds context by listing the areas the check covers, which gives meaning beyond an empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses 'read-only Ascend/CANN environment check' which clearly identifies the operation as a query and specifies the resource. It lists concrete items checked (devices, HCCL preload, Docker hints), differentiating it from sibling health/status 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?

The description implies this is a read-only environment inspection tool but does not explicitly state when to choose it over sibling tools like repository_health or collective_status. There's no stated alternative or exclusion, so usage context is implicit.

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?

No annotations are provided, so the description carries the burden of disclosing behavior. It indicates the tool is a one-shot session initializer and lists the data returned, but it does not state whether this is read-only or has side effects, nor does it describe any caveats like caching or resource intensity.

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, front-loaded with the key concept 'Single-call session bootstrap' and immediately enumerates the included elements. No filler or 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 presence of an output schema and full parameter descriptions, the description adequately covers return values and parameters. However, it lacks explicit usage context and behavioral transparency, making it slightly incomplete for an agent deciding whether to invoke this tool.

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

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

The input schema covers all three parameters with detailed descriptions, and the schema description coverage is 100%. The description itself does not add parameter-specific details but does mention the aggregates (route metadata, health, program hints) that correspond to the tool's output, which indirectly relates to parameters like include_health.

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 uses a specific verb ('bootstrap') and names the resource ('session'), and enumerates the included components (route metadata, read_plan, health, program hints), making it clear what the tool does. However, it could more explicitly state the outcome of bootstrapping or how it differs from calling these components separately.

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 this is a consolidated single-call alternative to several sibling tools, but it provides no explicit 'when to use' or 'use instead of' guidance. There is no mention of scenarios where this tool is preferred over route_task, read_plan, or repository_health individually.

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 and does disclose a key behavioral trait: it is read-only and never writes to the source doc. However, it does not mention error behavior, response format, or how filters interact with the status matrix, leaving some behavioral aspects opaque.

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 conveys the tool's subject, source, and read-only nature without waste. Every part 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?

Despite having no annotations, the description provides the source document path, the nature of the data (merged/planned/gap), and the read-only guarantee. An output schema exists, so return-value details are not the description's responsibility. This is complete for a low-complexity status query tool.

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

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

The input schema describes both parameters fully with examples and substring-match semantics, yielding 100% schema description coverage. The description adds no additional parameter meaning, 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 identifies the tool's purpose: returning collective-comm feature parity status (merged/planned/gap) from a specific source file. It lacks an explicit action verb like 'get' or 'list', but the resource and scope are unmistakable and distinguish it from sibling tools like program_status or read_doc.

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 is implied by the tool name and description (query collective-comm parity status), but there is no explicit statement of when to prefer this over alternatives, nor any exclusions. The read-only note is a mild usage caveat, but no clear contextual guidance is provided.

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. It does disclose the scope of abstractions covered, which adds useful context. However, it does not mention potential side effects (likely none as an explain tool), output format, or any limitations, though these are partially mitigated by the presence of 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 description is one sentence, front-loaded with the action and resource, and includes concrete examples. It is highly concise with no fluff, earning a top 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?

Given the tool's simplicity (one well-documented parameter) and an output schema, the description is mostly sufficient. However, the overlap with sibling tool 'explain_pass' is unresolved: since 'passes' are explicitly listed, it's unclear when to pick 'explain_abstraction' over 'explain_pass'. This missing differentiation affects completeness.

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 provides 100% coverage for the single 'name' parameter with a detailed description and examples, so the baseline is 3. The tool description itself adds no extra parameter meaning, but the schema already handles it well, so no further deduction is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Explain' and the resource 'stack abstraction', listing concrete categories (IR/passes/codegen/ISA/runtime or Ascend hardware) with examples. This distinguishes it from sibling tools like 'explain_pass' by covering a broader scope while still being specific.

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 guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, preconditions, or scenarios where a different tool (e.g., 'explain_pass') would be more appropriate. The schema parameter description hints at using 'search_abstractions()' first, but the main description lacks usage context.

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?

No annotations are provided, so the description must carry the transparency burden. It conveys that the tool is explanatory and scoped to the Default pipeline, and lists the facets it reports, but it does not disclose error behavior, output format, or side effects beyond what the verb 'explain' implies. The lack of a read-only flag or edge-case notes leaves some gaps, but the read-only nature is strongly inferred.

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 states the verb, resource, and covered aspects with no wasted words. It is maximally concise while preserving necessary 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?

For a simple one-parameter tool with an output schema (not shown), the description covers the essential context: what it explains, the scope (Default pipeline), and the specific dimensions it covers. It lacks explicit usage guidelines, but given the tool's simplicity and the presence of an output schema, it is sufficiently 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?

The input schema provides 100% coverage for the single parameter 'name' with a clear description and example. The tool description adds no additional parameter-level detail beyond what the schema already 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 uses a specific verb 'Explain' and identifies the resource as 'a pass in the Default pipeline', then enumerates the covered aspects (order, phase, neighbors, verify tasks). This clearly differentiates it from sibling tools like explain_task or explain_abstraction.

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 ('explain a pass in the Default pipeline') but does not explicitly state when it should be preferred over alternatives or provide exclusions. There is no mention of sibling tools or criteria for selection.

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

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

No annotations are provided, so the description carries the burden of signaling safety. The verb "Show" implies a read-only inspection and does not suggest mutation or execution. However, it does not explicitly state that the task is not executed or that no side effects occur, which would be valuable for a tool with no annotation support.

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 concise sentence that immediately states the tool's purpose. There is no filler or repetition of schema/annotation 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?

This is a simple two-parameter inspection tool with a complete input schema and an output schema present. The description sufficiently identifies what the tool returns: the exact command and metadata for a named task. It could add a note about non-execution, but overall the definition is adequate.

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 schema already documents repo and task well, including the instruction to always specify repo. The tool description adds contextual framing but no additional parameter-level 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?

Description uses a specific verb and resource: "Show the exact command and metadata configured for a named task." It clearly indicates inspection of task configuration. It does not explicitly differentiate from siblings like list_tasks or explain_pass, but the "exact command and metadata" phrasing makes the intent fairly 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?

No guidance is given about when to use this tool instead of siblings such as list_tasks, run_task, or explain_pass. The context is clear only in a general sense, but there are no exclusions or alternatives mentioned.

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 must disclose behavioral traits but only says 'Find', implying a read-only operation. It does not explain what the tool returns, how the optional area affects results, or any error behavior. The description adds minimal context beyond the purpose.

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 that is front-loaded with the primary action and resource. It contains no redundant words, and every element contributes to understanding the tool's scope, making it highly concise.

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 that an output schema exists and the input schema fully documents parameters, the description is adequate for a simple lookup tool. It could benefit from a brief usage note, but the schema fills in the gaps, making the description reasonably 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?

The input schema has 100% parameter description coverage, including the instruction that 'repo' comes from list_repositories() and that 'area' can be left empty to list all areas. The tool description merely repeats the optional area concept with the same examples, adding little beyond the schema. 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 with a specific action ('Find') and resource ('code entrypoints'), scoped by 'repo' and optional 'area'. It distinguishes the tool from siblings like search_code and list_repositories, though it does not explicitly name alternatives.

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 usage guidelines are provided in the description. It does not indicate when to prefer this tool over alternatives such as search_code, nor does it mention prerequisites like retrieving the repo name from list_repositories(). The only usage hint appears in the schema parameter description, not in the main description.

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?

Without annotations, the description carries the full burden. It says 'generate a bash script' but doesn't disclose whether the tool executes the script, writes a file, or prints to stdout; doesn't mention side effects, permissions, or the meaning of 'safe.'

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 entire description is one clear sentence, front-loading the action and outcome. It's concise without unnecessary 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?

Despite the workflow complexity (7 flags, multiple stages), the description only lists stages without explaining output format, behavior when flags are off, or what 'safe' means. With schema covering parameters and an output schema presumably present, it's adequate but leaves gaps about the script generation behavior.

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?

All seven parameters have descriptive schema entries, providing 100% coverage. The tool description names the workflow stages but doesn't map them to specific parameters; schema descriptions already cover semantics like 'Skip sim Docker tests' and 'Branch to rebase onto.'

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 uses the specific verb 'Generate' and identifies the resource as 'a bash script' for the 'rebase->pre-commit->sim-Docker-tests->squash->push gate workflow,' clearly distinguishing it from execution-oriented siblings like run_command or run_task.

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 when-to-use guidance is provided. It doesn't mention when to use this instead of run_command or explain_task, nor any prerequisites or 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 burden of behavioral disclosure. It does not state whether the tool writes to a file, prints to stdout, modifies container state, or requires specific permissions. The phrase 'in a container' is vague about 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?

One concise, front-loaded sentence communicates the core function without waste. It is appropriately sized for the tool's simple primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, covering return values, but the description lacks behavioral context and usage guidance. For a tool with 7 parameters, this single-sentence description is minimal but not entirely inadequate; it provides the essential purpose.

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 baseline is 3. The description does not add any extra meaning to parameters; it only mentions the overall purpose. No additional detail beyond the schema is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Generate markdown handoff'), the resource ('developer NPU verification'), and the context ('in a container'). This distinguishes it from siblings, as no other sibling tool is about generating handoffs.

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 for creating a handoff for developer NPU verification, but it does not provide explicit guidance on when to use this tool vs alternatives, nor does it mention any exclusions or prerequisites like container readiness.

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 must carry behavioral disclosure. It hints at potentially large diffs via the stat_only recommendation and describes output, but does not explicitly state that the operation is read-only, mention error conditions, or explain repo requirements—though 'git diff' strongly implies non-mutating 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, efficient sentence that front-loads the primary function ('Return the git diff for a repository') and includes a valuable usage tip without any 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 simplicity, full schema coverage, and presence of an output schema, the description is sufficient for core understanding. It lacks explicit alternative tool guidance, but the purpose and a key usage recommendation are clear, making it complete for this complexity level.

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 descriptions cover 100% of parameters, providing a baseline of 3. The description adds meaningful guidance beyond the schema by recommending stat_only=True for orientation, which gives contextual purpose that the schema's 'useful for large diffs' does not fully convey.

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 returns the git diff for a repository, specifying both stat and optional patch. It distinguishes from siblings like git_log and read_file by naming a specific git operation and its output scope.

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

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

The description offers a concrete usage recommendation ('Prefer stat_only=True for orientation'), providing context for when to use this parameter. However, it does not explicitly compare with alternative tools or state exclusions, so it falls short of full alternative 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 discloses that the tool returns structured data with specific fields (sha, author, date, message), which is helpful. It implies read-only behavior via 'Return' but does not explicitly state it. No side effects or limits are mentioned, but for a simple read operation this is adequate. No contradiction with annotations since none exist.

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, focused sentence that front-loads the purpose. Every phrase is meaningful, with no filler or redundancy. It is appropriately concise for the tool's simplicity.

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 output schema exists, so return values are covered elsewhere. The description explains the core function clearly. Minor gaps like default ref behavior and maximum N are handled in the input schema. Given the tool's low complexity, the description is sufficiently 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 all parameters (n, ref, repo) have descriptions. The description adds no additional meaning beyond the schema; it only restates that N commits are returned, which aligns with the schema. Baseline of 3 applies because the schema does the heavy lifting.

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 uses a specific verb ('Return') and clearly specifies the resource ('last N commits for a repository') and output format ('structured data (sha, author, date, message)'). This distinguishes it from siblings like git_diff (which focuses on changes) and repository_health (which assesses health).

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 guidance is provided about when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contextual hints like 'use for recent history instead of git_diff'. The description is purely functional and lacks usage direction.

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?

No annotations are provided, so the description must disclose behavior. It does add value by listing specific aspects it checks (missing paths, stale enriched docs, Ascend corpus, index build time), giving insight into its scope. However, it does not mention return format, side effects, or whether it performs any mutations, leaving some behavioral 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 entire description is a single sentence, front-loaded with the primary purpose ('Check knowledge config health') followed by a concise list of specific checks. Every word contributes to understanding the tool, with no redundancy or 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 simple nature (no parameters) and the existence of an output schema, the description covers the essential context: what the tool checks and its health-related domain. It could be slightly stronger by explicitly stating that it returns a health report, but the output schema mitigates that need. Overall, it is sufficiently complete for an agent to select and invoke 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?

The input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific information because none are needed, and the schema already fully covers parameter semantics with an empty object. The description meaningfully explains what the tool does, which is more relevant than parameter details in this case.

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 uses the specific verb 'Check' followed by the resource 'knowledge config health', and enumerates distinct checks (missing paths, stale enriched docs, Ascend corpus, index build time). This distinguishes it from sibling health tools like repository_health or collective_status, which focus on other domains.

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 phrase 'Check knowledge config health' clearly indicates the tool's context of use: when an agent needs to assess the state of knowledge configuration. It does not explicitly name alternatives or exclusions, but the specificity of the checks (e.g., Ascend corpus, index build time) implies this is the appropriate tool for knowledge-related health investigations.

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. The verb 'List' strongly implies a read-only operation, and the description explicitly states the categories of information returned. It does not disclose any side effects or edge cases, but for a simple list tool, the behavior is transparent enough.

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 states the verb and the four key objects. No unnecessary words or repetition; every word adds value.

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 low-complexity with no parameters and an output schema that defines return values. The description covers all the tool's purpose and scope, making it complete for an agent 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?

The tool has zero parameters, so the schema provides no information. The description adds meaning by specifying what will be listed, though it does not need to explain parameter syntax. Given the baseline of 4 for 0-parameter tools, this 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 uses a specific verb 'List' and enumerates four distinct types of resources (task routes, MCP resources, notes topics, and bootstrap prompts), clearly distinguishing it from sibling tools like list_tasks or list_repositories.

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 the tool is for retrieving an overview of knowledge topics, but it provides no explicit guidance on when to prefer this tool over alternatives like list_tasks or knowledge_health. The usage context is clear from the description, but no alternatives or exclusions are mentioned.

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 for behavior. It clearly conveys that this is a listing/read operation and indicates what will be returned, which is adequate for a simple tool. It does not explicitly state that it is read-only, mention side effects, or describe error cases, but for listing repositories the operation is self-evident.

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, well-structured sentence that immediately states the action and the output content. There is no fluff or redundant wording, and all words earn their 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 no-parameter list tool with an output schema available, the description covers the essential purpose and expected results. It does not mention scope or filtering, but given the tool's simplicity and the presence of an output schema, 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?

The tool has zero parameters and schema coverage is 100% vacuously, so the baseline for parameter semantics is 4. The description adds no parameter-specific detail, but none is needed since the input schema declares no properties.

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 ('List') and resource ('configured repositories'), and specifies the returned information: paths and architecture metadata. It is unambiguous about its core function. However, it does not explicitly distinguish itself from sibling tools like repository_health, so it stops 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?

The description gives no guidance on when to use this tool versus alternatives. It neither mentions prerequisites nor names siblings such as repository_health or list_tasks that might seem related. An agent must infer usage purely from the name and description, which is acceptable but leaves gaps.

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?

No annotations are provided, so the description must convey behavior. The verb 'list' implies a read-only operation, and the description mentions output contents (metadata, warnings), but it does not explicitly state side-effect-free behavior, error conditions, or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence with the verb and object front-loaded. No filler, every word contributes.

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 an output schema present, return values need not be explained. The description covers purpose and scope adequately for a simple list operation, but it could be slightly more explicit about when to use it relative to run_task or explain_task.

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% with both parameters well-documented (repo example, include_command default and meaning). The description adds no additional param semantics, so the baseline of 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 uses a specific verb ('list') with a clear resource ('available named tasks for a repository') and indicates content ('including metadata and warnings'). This clearly distinguishes it from sibling tools like run_task or explain_task.

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 schema provides a prerequisite (repo from list_repositories()) which gives clear context on when to call. However, the description itself does not explicitly mention alternative tools or when not to use it, so it lacks full exclusion 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 clearly states this is a 'Return' operation (read-only in nature) and adds context by indicating it returns one-line descriptions and is intended for specific tools. Given the simplicity of the tool (no parameters), this is sufficient transparency, though it doesn't explicitly state 'does not modify state'—inferred from 'list'.

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, well-structured sentence that front-loads the action and resource, followed by the purpose. Every word earns its place—no fluff or 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 simplicity (0 parameters) and the existence of an output schema, the description is complete. It conveys the tool's purpose, scope, and immediate use case, leaving no significant gaps for an agent to misinterpret.

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 meaning by explaining the output and its intended usage, which indirectly explains why no parameters are needed (it returns all valid values globally).

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 uses a specific verb ('Return') and a clear resource ('all valid task_type values') with a stated purpose ('for use with bootstrap_session and route_task'). It distinguishes itself from sibling tools like list_tasks by focusing on task_type values specifically and naming the intended consumer 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?

The phrase 'for use with bootstrap_session and route_task' provides clear context for when to invoke this tool, implying it should be used before those operations to obtain valid task types. No explicit exclusions or alternatives are mentioned, but the purpose is evident from the context.

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?

No annotations are provided, so the description carries the burden. It reveals the source file and output contents, implying a read-only operation, but does not explicitly state that it reads without side effects, nor mention error behavior if the file is missing.

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, immediately front-loaded with the purpose, and includes relevant details in parentheses. Every word earns its place with no waste.

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 zero-parameter tool with an output schema, the description sufficiently explains what the tool returns and from where. Minor gap: it does not mention what happens if status_prs.md is absent or how the output schema is structured, but the output schema is provided separately.

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, and the schema is empty. The description adds context about the output source and content, which is sufficient. The baseline for 0 params is 4.

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 provides structured PR/plan status from status_prs.md, listing specific content (open PRs, blockers, plan cross-index). It identifies a specific resource and content, but does not explicitly differentiate from sibling tools like collective_status or repository_health.

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: if you need PR/plan status from status_prs.md, this tool is appropriate. However, there is no explicit when-to-use vs alternatives, no exclusions, or named sibling tools for comparison.

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 full responsibility for behavioral disclosure. It mentions 'tier labeling' and section extraction, but does not describe error behavior (e.g., invalid section), permission requirements, side effects, or return format. The schema does provide some behavior cues (e.g., bad section shows TOC), but the description itself is too sparse to be 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?

The description is two short sentences, front-loading the primary action ('Read a workspace document'). Every word adds value; no filler or redundant information. Ideal conciseness.

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 presence of a detailed input schema and an output schema, the description is mostly sufficient for a straightforward read tool. It lacks an explicit tie to the broader workflow (e.g., when to use tier labeling), but the schema compensates by covering path discovery and error behavior. The main gap is the absence of a clear 'when to use' context, but the tool is simple enough that a 4 is warranted.

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 quite detailed for all three parameters (path semantics, section extraction behavior, max_chars bounds). The description only adds a small clarifying clause ('extracts a markdown heading') which is largely redundant with the schema. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 ('Read a workspace document') with a distinctive feature ('tier labeling') and an optional section-extraction capability. This clearly differentiates it from sibling tools like read_file, which reads arbitrary files, and list_knowledge_topics, which discovers paths.

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 is implied: use this to read workspace documents. The schema's path description mentions using list_knowledge_topics to discover paths, which is a usage hint, but the main description does not explicitly state when to prefer read_doc over alternatives (e.g., read_file, search_code) or 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, the description carries the transparency burden. It discloses a meaningful behavioral trait: the tool reads files directly instead of shelling out, avoiding command execution side effects. It also states 'arbitrary' to indicate broad file access, though it does not discuss pagination 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 well-structured sentence, front-loaded with the action and resource, and no wasted words. Every phrase ('arbitrary', 'without shelling out') adds value.

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 straightforward file-read tool with a detailed input schema and an output schema, the description is sufficient to understand primary use. It could more explicitly differentiate from document-reading and search siblings, but the current wording is not misleading and covers the essential context for correct 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 descriptions cover 100% of the parameters with examples, defaults, and constraints, so the description adds little beyond the schema. It provides context (source file, repository) but no field-level semantic detail beyond what the schema already offers.

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 uses a specific verb ('Read'), a concrete resource ('arbitrary source file'), and a scope ('from a repository'). The qualifier 'without shelling out' distinguishes it from shell-based tools like run_command, making the purpose immediately clear.

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 appropriate use for direct, non-shell file reads and excludes shell execution as a mechanism. However, it does not explicitly name sibling alternatives (e.g., read_doc for documentation or search_code for searching), so it stops short of full alternative 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns three specific data points per repo, which is helpful, but it does not explicitly state that it is a read-only operation or mention any prerequisites, edge cases, or side effects. This is a moderate level of transparency for a simple health check 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?

The description is a single sentence of 13 words that directly states the action and the data returned, with no filler, repetition, or unnecessary detail. It is an example of concise, front-loaded writing.

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 (1 parameter, output schema present, read-only purpose), the description adequately states its primary function. It doesn't cover use-case guidance or explicit safety notes, but these are also addressed in other dimensions. The essential behavior is complete for a tool of this complexity.

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% for the only parameter (include_clean), which has its own description. The tool description does not add any parameter-specific meaning beyond what the schema already 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 uses a specific verb 'Get' and names concrete resources: branch, dirty state, and ahead/behind. It clarifies scope with 'every configured repo,' making it clearly distinct from sibling tools like list_repositories (which likely only lists names) or git_log/git_diff (which focus on log/diff).

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, nor are exclusions or alternative tool names mentioned. However, the description implies a use case (querying overall git status of all repos), so usage is implied rather than absent.

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 of behavioral disclosure. It does imply a read-only operation via 'Return', but it does not explicitly state whether the tool modifies any state, how errors are handled, or what the output structure looks like. This is a significant gap for a routing tool that might have side effects or require specific preconditions.

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, focused sentence that communicates the core output without any filler or redundancy. It is front-loaded with the key action and resources, making it easy to parse quickly.

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 sufficient for a basic understanding but lacks important context such as how task_type influences the returned artifacts, what 'read-first' means in practice, and when a user would invoke this tool instead of directly reading docs or listing tasks. An output schema exists, so return values need not be detailed, but the purpose and workflow integration remain underspecified.

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 description coverage is 100%, with both parameters (task_type and detail) adequately documented in the input schema. The description itself does not add any parameter semantics beyond the schema, so the baseline of 3 applies. The task_type parameter's cross-reference to list_task_types() in the schema already provides helpful context.

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 ('Return') and resource types ('read-first docs, rules, entrypoints, and verify tasks') for a compiler workflow. This unique combination distinguishes it from sibling tools like read_doc, list_tasks, find_entrypoints, and verify_ladder, which each handle one of these outputs individually.

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 no guidance on when to use this tool versus alternatives such as list_task_types, run_task, or explain_task. It does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer appropriate usage from the name and schema alone.

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?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: build/test commands are refused without an NPU, while read-only commands are unaffected. It also notes destructive patterns are blocked (in the schema). This adds meaningful context beyond the basic purpose, though it doesn't fully detail output or 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?

The description is efficiently structured with a one-sentence purpose up front, followed by a second paragraph of specific behavioral constraints. Every sentence earns its place with no filler or repetition.

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 (arbitrary shell command execution) and the existence of an output schema and full parameter schema, the description is quite complete. It covers usage alternatives, key restrictions, and the NPU-specific behavior. It could elaborate slightly on return values, but the output schema mitigates that 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 coverage is 100%, so the baseline is 3. The description enriches parameter understanding by clarifying the 'command' parameter's constraints (e.g., refusal of build/test commands under no-NPU conditions) and the 'repo' parameter's cwd behavior. This adds value beyond the schema alone.

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: 'Run an ad-hoc shell command in a repository.' It clearly distinguishes from siblings by explicitly recommending run_task for known tasks and git_log/git_diff/read_file for read-only operations, establishing this tool as the fallback for arbitrary commands.

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 explicit usage guidance: 'Prefer run_task for known tasks or git_log/git_diff/read_file for read-only operations.' It also warns that build/test commands are refused when no NPU is reachable, giving clear when-to-use and when-not-to-use context.

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 transparency burden. It reveals non-obvious conditional behavior: host execution when NPUs are available, sim Docker re-routing otherwise, and refusal with guidance when no sim image exists. This is valuable, though it omits potential side effects like file modifications or stdout/stderr 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 two paragraphs and front-loaded with the core purpose, followed by important routing details. It is concise and each sentence contributes, though the internal reference 'see _SIM_RUN' is slightly opaque.

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 task runner with no annotations, it covers the critical routing logic and refusal cases, and references list_repositories()/list_tasks() for parameter semantics. Output schema handles return-value documentation, but the description lacks explicit sibling differentiation and discussion of failure modes beyond no-sim-image.

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 detailed parameter descriptions (e.g., extra_args appended verbatim, timeout range 1–7200). The description adds no parameter-level meaning beyond what the schema already provides, so 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 'Run a configured task in a repository' with a specific verb and resource, and the routing details further specify it executes build/test tasks. This distinguishes it from arbitrary command running (run_command) and other sibling 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?

The description provides contextual behavior (NPU-based routing) but does not explicitly state when to prefer this tool over alternatives like run_command or route_task, nor does it offer exclusions or clear use-case boundaries beyond those implicit in 'configured task'.

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. It discloses the ranking order, which is a useful behavioral trait. However, it does not explicitly state the operation is read-only or describe any potential side effects, though that is implied 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?

The description is two sentences, front-loaded with the core action and the ranking rule. Every sentence is informative and concise, with zero waste or repetition.

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 search tool with an output schema available, the description covers the main purpose and ranking detail adequately. The only gap is that it does not mention usage context relative to sibling tools, but given the simplicity and schema support, it remains complete enough 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 baseline is 3. The schema already explains `query`, `fields` (summary/full), and `max_results` (1-100). The description adds no additional parameter semantics beyond what the schema provides, so a 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 'Search the abstraction index by keyword,' identifying the specific verb and resource. It distinguishes from sibling tools like `search_code` by targeting the abstraction index, and the ranking criteria (exact name > name-contains > tag > layer/kind) further clarifies scope.

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

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

Usage is implied as a keyword search for abstractions, but there is no explicit guidance on when to use this tool over alternatives like `search_code` or `read_doc`. No exclusions or alternative references are provided, so it lacks direct 'when vs. when-not' 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 burden of disclosure. It does explain the mode behavior (locations omits line text, context includes it), but repeats information already in the schema. It does not mention other behavioral traits such as default repo scope, regex handling, or result limits, which are only in the schema. The added value beyond structured fields is minimal but not misleading.

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, front-loaded with the tool's purpose and a concise summary of the mode options. Every sentence serves a purpose and there is no redundancy or 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?

Given the rich input schema (100% coverage) and the presence of an output schema, the description is adequate for a straightforward search tool. However, it lacks any mention of how this tool relates to sibling tools like search_abstractions, leaving a minor gap in contextual understanding.

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 baseline is 3. The description repeats the mode parameter's behavior without adding any new meaning or context for the other seven parameters, so it does not improve on 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 searches code across repositories, using a specific verb and resource. It is immediately understandable, but does not explicitly distinguish from the sibling tool 'search_abstractions', so it lacks sibling differentiation.

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 no guidance on when to use this tool versus alternatives like search_abstractions. It only states what the tool does, not the conditions or contexts that would make it the preferred choice.

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?

No annotations are provided, so the description must disclose safety and side effects. It only says 'Summarize' without clarifying whether it is read-only, what operations it performs on the directory, or how results are presented. This leaves the agent without key behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the verb 'Summarize', and contains no filler. It is appropriately sized for a simple 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 the low complexity and the presence of an output schema, the description covers the core purpose and parameter. However, it lacks behavioral transparency and explicit usage guidance, making it minimally adequate but not comprehensive.

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 thoroughly documents the single parameter 'run_dir', including path types. The description adds that the directory contains results.json and anomalies, which aligns with the schema but does not extend it significantly.

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 uses the specific verb 'summarize' and names the resource 'pypto-profiling campaign directory', with concrete contents (results.json, anomalies). This clearly distinguishes it from sibling tools focused on code, tasks, and repositories.

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 tool's purpose clearly implies when to use it (whenever a profiling campaign summary is needed), and no sibling offers a similar function. However, it does not explicitly state when not to use it or mention 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?

No annotations are provided, so the description carries the full burden. It discloses the tool's behavioral scope well: it is an 'enriched' cross-layer trace that produces multiple categories of results, and it contrasts its heavier behavior with a lightweight sibling. It stops short of explicitly stating whether the operation is read-only or has side effects, rate limits, or failure modes, but for a trace/lookup tool the risk is low and the added context is substantial.

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 three short, information-dense sentences. The first sentence states the core behavior and output scope, and the next two provide differentiation and usage direction. There is no filler or repetition.

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's enumeration of return categories is valuable and mostly complete: it tells the agent what the trace covers and when to use it. The only missing context is explicit caveats such as read-only status, potential cost/complexity of running a full cross-layer trace, and what happens when no matching contract is found. These are minor for a single-parameter 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 single parameter symbol_or_path is already well-described in the schema with examples and matching semantics. The description adds no additional parameter-level details, but with high schema description coverage the baseline of 3 is appropriate; the schema does the necessary work.

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 starts with 'Full cross-layer trace' and enumerates specific outputs: stack location, contract triangle, cross-layer verify tasks, and active-PR links. It also explicitly differentiates from the sibling trace_in_stack, calling this the 'enriched trace' versus a 'lightweight stack-location-only lookup.' An agent can immediately understand what this tool does and how it differs from the closest alternative.

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 direct usage guidance: use this tool when the enriched cross-layer trace is needed, and use trace_in_stack for a lightweight stack-location-only lookup. This explicit when/when-not pairing with a named alternative is exactly what an agent needs to choose correctly.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It reveals the tool is lightweight, limited to abstraction card or path-prefix matching, and excludes contract artifacts and PR links—useful behavioral context. However, it does not state read-only nature, outcome when no match is found, or operational details of the matching modes.

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?

Two sentences with zero waste. The first sentence fronts the core behavior and scope; the second states the exclusions and points to the alternative. Excellent structure for quick agent parsing.

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 tool with an output schema and a clear sibling list, the description covers the essential boundaries: what is matched, what is excluded, and where to go for richer traces. It lacks a positive 'use this when' statement, but the negative scoping and sibling pointer make the tool usable without further inference.

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 fully describes the parameter with 100% coverage, including path-prefix matching for file paths and abstraction card matching for concept names. The description restates the same concepts without adding new meaning, 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?

The description states a specific scope: lightweight stack location via abstraction card or path-prefix pipeline matching. It clearly differentiates from sibling trace_contract by explicitly noting what it does not include (contract artifacts, PR links). The verb is somewhat implicit, but the resource and limitations are clear.

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 names trace_contract as the alternative for enriched cross-layer traces and notes exclusions ('No contract artifacts or PR links'), which informs when not to use this tool. It does not give a positive condition like 'use when you only need lightweight location', but the contrast is sufficient.

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 discloses the conditional return of static_checks and the ordering relative to pytest tasks. However, it doesn't state whether the tool executes anything (though 'Suggest' implies non-execution) or describe behavior for non-C/C++ paths, leaving some 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?

Two concise sentences convey purpose, a conditional, an example, and a cross-reference without redundancy. Each clause adds value.

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 tool with a rich schema and an output schema, the description adequately covers the main use case and key conditional logic. It could mention the empty-list case, but the output schema likely covers return structure, making this sufficiently 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?

The schema already provides a thorough description of changed_paths, including examples and purpose, covering 100% of the parameter. The tool description adds no additional parameter detail beyond referring to 'changed file paths', so 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 verb 'Suggest' and the resource 'minimal verify tasks' scoped to 'changed file paths', distinguishing it from generic task-listing siblings. The conditional return detail further clarifies its specialized behavior.

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 a clear when-to-use condition: for changed paths, and specifically instructs to run static_checks before pytest tasks for C/C++ files. It references tools/clang_tidy_workflow for additional context, though it doesn't explicitly name alternatives.

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