TheaOS mcp

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

Annotations already cover read-only, idempotent and non-destructive, and the description partly repeats 'Read-only'. What it adds beyond annotations is 'the exit code is the verdict' — the agent learns the tool reports through exit status rather than content, plus that each entry carries the guard that stops the mistake. Return shape is only sketched.

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 tight sentences, front-loaded with what the tool returns before the scoping requirement. Dense domain jargon ('shapes', 'tells', 'guard') costs some readability but nothing is padding.

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

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

There is no output schema, so the description is the only source of return-shape information, and it only says entries come 'with the guard that stops it' plus an exit-code verdict. Given four parameters, a default `limit`, and no annotations about payload format, an agent still cannot predict what an entry looks like.

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 all four parameters, and the description largely restates those meanings (file for `for`, error text for `match`, one shape's `id`). The `limit` parameter and its default of 3 are never mentioned in the description, so it adds no meaning the schema doesn't already carry.

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 concrete resource (recorded agent mistakes with their stopping guard) and the two scoping axes (file via `for`, error text via `match`). It also states what the tool does NOT do ('the whole ledger is not offered'). It never names the obvious counterpart `successes`, so sibling differentiation is left to the agent's inference.

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 tells the agent it must scope results with `for`, `match` or `id`, which is implied usage guidance, but gives no when-to-use/when-not framing and no comparison to siblings like `successes` or `proof`. The one exclusion is about scope, not about tool selection.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower, yet the description still adds real value: it explicitly states the command is NOT executed and that the result includes a state plus an argv form. The closing line 'the exit code is the verdict' hints at how the result is consumed but is ambiguous for a tool that does not run anything.

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 sentences with the core behavior front-loaded and no filler. The compression comes at some cost to readability – 'as argv, with its state' is dense and the exit-code clause sits oddly in a description of a non-executing 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 must carry the return contract, and it only gestures at it ('as argv, with its state'), leaving the structure of 'state' and the meaning of the exit-code verdict unclear. For a read-only lookup tool the gaps are survivable, but an agent would still not know exactly what it receives back.

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 schema already documents all three parameters, including the important 'omit gate for every gate the change needs' behavior. The description only implicitly touches on the gate and path parameters ('a named gate ... for a file') and adds nothing about the change class default.

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 says it returns 'the one command a named gate runs for a file, as argv, with its state' – a specific resource and output shape, though the verb is implicit (it's a lookup, not an action). It never distinguishes itself from the many sibling tools (headron, port, route, proof), and a reader must infer that 'gate' is a config-defined check rather than anything else.

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 shows the command and does not run it' implies a dry-run/inspection use case, which is the closest thing to guidance here. There is no explicit when-to-use, no when-not-to-use, and no named alternative; the routing information about omitting the gate parameter lives only in the schema, not the 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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds that the exit code is the verdict plus how to discover subcommand arguments. It does not describe batch execution behavior or any permission/rate-limit considerations, but with annotations covering safety this is a solid 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?

The description is front-loaded with the core behavior and an example, then supplies the verb list and discovery command. The long verb list is dense but useful for a dispatcher; overall it is appropriately sized, though slightly list-heavy.

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 generic command-dispatch tool with no output schema, the description covers verb discovery and exit-code interpretation. It is still incomplete because batch/parallel usage and the relationship to sibling tools are not clarified, which an agent would need to call it optimally.

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 low at 33%, and the description only explains argv via the example and 'one command' phrasing. The batch parameter, including its max-8 grouping behavior and how it relates to argv, is not described in the tool description, leaving a significant semantic gap.

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 dispatch behavior: run one read-only headron command as argv, with an example and a full verb inventory. It is clear what the tool does, though it does not explicitly distinguish itself from dedicated sibling tools such as gate, port, or route.

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

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

It gives useful in-tool guidance via ["commands", "--json"] for discovering arguments, which is a concrete usage pattern. However, it does not say when to use this generic runner versus the sibling wrapper tools, nor 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety behavior is covered. The description adds little beyond saying it uses the 'Mind API orchestration layer' and does not explain classification output, risk levels, or failure 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?

It is a single front-loaded sentence with the operation stated first. The phrase 'using the Mind API orchestration layer' is mildly non-essential but not enough to make it verbose.

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 read-only tool with rich annotations, the description covers the core action. However, there is no output schema and the description does not explain what the classification returns, so interpretation of results is left implicit.

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 'files' parameter, and its schema description already says 'files to process'. The description adds that files are classified by change type and risk level, but gives no extra format or per-file expectations.

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 gives a specific verb, 'Classify', and resource, 'files', plus the dimensions 'change type' and 'risk level'. It is clear what the tool does, but it does not explicitly distinguish itself from any sibling 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?

There is no explicit guidance on when to use this tool, when not to use it, prerequisites, or alternatives among the siblings. The agent must infer usage from the phrase 'Classify files' 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description adds no behavior beyond that framing — no cost/latency hint for a bundled multi-step operation, no statement of what the combined result contains, no indication of whether sub-steps are executed or merely reported. For an orchestration tool whose main risk is redundant downstream calls, this is thin.

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 with no filler, but it is a dense jargon stack ('classification, gates plan, agent route, policy rules, search hits') that front-loads abstract nouns rather than the operative behavior. Short, yet not efficient at conveying the key fact.

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

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

There is no output schema, so the description is the only place the return value could be explained — and it merely lists five categories of information without indicating their shape, nesting, or how an agent should act on them. Given the tool's combinatorial nature, that is a substantial 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?

Only one optional parameter and schema description coverage is 100% ('files to process'), so the schema carries the load. The description never mentions the files parameter or how file scope affects the orchestration, but with full coverage the baseline 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 identifies this as a combined 'one-shot orchestration directive' aggregating classification, plan, route, policy and search results, which distinguishes it in spirit from the narrower siblings (mind_classify, mind_plan, mind_route, mind_search). But it is a noun phrase with no verb and no statement of what the tool actually does when called — 'combining' is a label, not an action. An agent gets the gist but not a crisp 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?

Nothing says when to use this one-shot tool versus calling mind_classify, mind_plan, mind_route and mind_search individually, nor any preconditions or exclusions. The sibling list makes the alternative path obvious, yet the description never routes the agent between them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds useful context by enumerating the telemetry dimensions returned. It does not discuss auth, rate limits, or output format, which is acceptable given the annotation coverage.

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 front-loaded sentence with zero waste. The key resource and payload are stated immediately.

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

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

Complete for a simple, no-parameter health-check tool: it names the returned telemetry components and annotations cover safety. Minor gap: exact response shape is not described, but no output schema exists and the listed contents are 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?

The tool has zero parameters and schema coverage is 100%, so there is no parameter semantics to document. Baseline for a zero-parameter tool 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?

States a specific verb (Show) and resource (Mind API health telemetry), then names the exact contents (session state, classification counts, system status). This clearly distinguishes it from sibling tools like mind_classify and mind_plan.

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?

Implied usage for health monitoring and diagnostics, but the description does not explicitly say when to use this tool versus any sibling or when not to use it. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful output context by saying the plan lists gates and isolation needs, but it does not explain the relationship between the optional files input and plan generation.

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 with no filler. It delivers the core action and plan contents 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?

For a low-complexity read-only tool with one optional parameter, rich annotations, and no output schema, the description is mostly complete: it names the output and its key contents. A small gap remains in not clarifying how the optional files parameter shapes the generated plan.

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?

There is one optional parameter ('files') with 100% schema description coverage ('files to process'). The description does not elaborate on parameter semantics, but the schema already provides the available meaning, so a 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 states a specific verb ('Generate') and resource ('verification plan for classified changes'), and adds what the plan contains ('gates and isolation needs'). It does not explicitly distinguish this tool from siblings like mind_classify or mind_route, but the purpose is 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 phrase 'for classified changes' implies a precondition and therefore implied usage, but the description does not explicitly say when to use this tool instead of alternatives such as mind_classify or mind_route. No exclusions or alternative-routing guidance are 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?

The annotations already establish that this is a safe, idempotent, non-destructive read operation, so the description does not need to carry the full safety burden. It adds that the operation gathers and verifies receipts over time, but it does not explain what verification entails, how far back the receipts go, or what the return format looks like.

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

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

The definition is a single front-loaded sentence with no wasted words. It states the action and resource immediately, which is appropriate for a zero-parameter read tool.

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

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

The annotations cover the safety profile and the tool has no parameters, but the description remains thin on what "audit receipts" are and what "verify" means in practice. For a tool whose purpose is auditing and verification, additional context about the returned evidence or time scope would make the definition more 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 tool has zero parameters, so parameter semantics are inherently simple and the baseline is 4. The description does not need to explain any input fields, and the empty schema is consistent with the 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 gives a specific verb pair, "Gather and verify," and a specific resource, "audit receipts from Mind API operations over time." It is clear enough to distinguish this from generic health or route tools, but it does not explain how it differs from nearby siblings such as proof, successes, or failures.

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 no explicit guidance on when to use this tool versus alternatives. The phrase "over time" implies an audit or historical usage scenario, but it never states exclusions or names siblings like proof or mind_health as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds that selection is gated on capabilities and permissions, which hints at an authorization step, but it never says what happens when no agent qualifies, whether a decision is recorded (cf. mind_receipts), or what the tool returns.

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 front-loaded sentence with no filler or repetition. It is tight, though the brevity comes partly at the cost of missing routing detail rather than being fully earned.

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

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

No output schema exists, so the description should explain what a selection yields (agent identifier, permission scope, why an agent was chosen) and how the result is consumed downstream. It also omits selection criteria in any concrete terms, leaving the core contract of the tool 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?

Only one optional parameter with 100% schema description coverage ("files to process"), so the schema carries the documented burden and baseline 3 applies. The description does not clarify whether the files are the "classified change" being routed or inputs the selected agent will consume, leaving the parameter's role ambiguous despite coverage.

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

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

Names a specific verb ("Select") and object ("authorized agent"), which is more than a restatement of the name. But "classified change" is unexplained jargon and the description never connects it to the only parameter (files), nor does it distinguish this tool from siblings like route, gate, or mind_direct, which plausibly overlap.

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 statement of when to use this instead of route, gate, mind_direct, mind_plan, or mind_classify. Given the crowded mind_* family, an agent has no basis in the description for choosing this tool over a sibling.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds two useful facts beyond them: retrieval is hybrid and runs against a local index (no network fan-out), but it says nothing about result ordering, result counts, or index staleness.

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 front-loaded sentence with no wasted clauses; the core mechanism arrives first. "Fast" is mildly promotional but costs little.

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, fully annotated, read-only search tool with no output schema, the description covers what the tool is and how it retrieves. Only guidance on result shape or when to reach for it over the mind_* siblings is missing, which is minor at 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?

Only one parameter and schema coverage is 100%, with the schema itself saying "search query or symbol," which the description echoes by noting symbol search is supported. Baseline 3 applies when the schema carries the load; the explicit mention that symbols as well as natural-language terms are valid adds a small amount of meaning.

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 concrete verb and resource ("search across Headron") and even names the retrieval mechanism (hybrid TF-IDF plus symbol search over a local index), so an agent knows exactly what the tool does. It stops short of naming a sibling or scoping what 'Headron' contains, so it is clear but not explicitly differentiated from the routing/gate family.

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 only implied: an agent can infer 'use this to find things in Headron,' but there is no statement of when to prefer it over port, route, gate, or mind_route, and no prerequisites or exclusions. Minimum-viable guidance without routing logic.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description correctly reinforces 'Read-only' without contradiction. It adds useful behavioral context beyond the annotations by explaining what the tool returns and that 'the exit code is the verdict,' though it does not detail exit-code values or failure 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?

The description is front-loaded with the critical instruction 'START HERE before editing a file' and then lists the useful outputs. Every clause carries information, and there is no filler.

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

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

With only two fully documented parameters, no output schema, and clear read-only annotations, the description is nearly complete for guiding an agent. It lists the categories of information returned and notes the exit-code verdict, though it could say more about how to interpret that exit code.

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

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

Schema description coverage is 100%, so both parameters are documented in the input schema. The description adds no parameter-specific meaning beyond implying that a file can be the subject. The baseline of 3 is appropriate when the schema fully documents 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 clearly states that the tool is the first step before editing a file, returning its route, tier, gates, lessons, and next commands. It distinguishes itself from siblings like route and gate by positioning itself as the entrypoint that surfaces all of those things together, though the name 'port' remains ambiguous without the description.

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

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

It gives clear timing guidance: 'START HERE before editing a file.' This tells the agent exactly when to use it. It does not name alternative tools or state when not to use it, but the context is strong enough to guide invocation.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add context — and it does: it declares the result is deterministic and that the exit code is the verdict, which tells the agent how to interpret the outcome. It stops short of explaining what the returned scope object looks like or how `--verify` interacts with this MCP surface.

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 sentences, front-loaded with the core purpose and with zero filler. The vocabulary is dense but each sentence carries a distinct fact (what it computes, where verification runs, how to read the result).

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

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

There is no output schema, so the description must convey return content — and it does via 'change class, planned gates and tools' plus the exit-code verdict. Minor gap: it doesn't clarify how an MCP caller (as opposed to a CLI user) observes that verdict or the scope payload.

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 all three parameters (`path`, `task`, `change`) are already documented in the schema. The description reinforces the 'one file' scope of `path` and the notion of change class, but adds no format or constraint detail beyond the schema, 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 names a specific capability: computing the deterministic scope of a change to one file, returning its change class plus planned gates and tools. That is concrete enough for an agent to know what it gets back. It does not, however, distinguish itself from siblings such as `gate`, `route`, or `steps`, which sound like adjacent planning/verification 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 clause 'Measured verification (`--verify`) runs gates and stays on the CLI' implies this tool scopes/plans while actual gate execution happens elsewhere, which is useful routing information. But it never says explicitly when to call `proof` versus `gate` or `route`, and gives no prerequisites or exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' in the description is redundant. The phrase 'the exit code is the verdict' is cryptic and does not clarify the return shape, whether it merely diagnoses or also applies a rule, or what 'what else decides it' means operationally.

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 short sentences with no waste, which is good, but the second sentence is opaque rather than informative, so brevity here costs clarity instead of earning it.

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

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

With no output schema, the description must explain what the agent gets back. Instead it offers the ambiguous 'exit code is the verdict', leaving the result shape, the meaning of 'what else decides it', and the diagnostic value undefined.

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%, but the single parameter's documentation is only the word 'path', adding nothing. Per calibration, full coverage sets the baseline at 3, and the description provides no additional semantics for the path (format, absolute vs relative, resolution base).

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 explains how a path was resolved (which pack, card, manifest, rule), which is more than the bare name 'route'. However, it is phrased as a fragment ('Which pack... resolved a path') rather than a stated verb+resource, and it does not distinguish it from the similarly named sibling mind_route.

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 on when to invoke this versus siblings such as mind_route, gate, or port. The only hint is the implied 'explain a resolution' use case, which the agent must infer.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds one genuinely new behavioral fact — 'the exit code is the verdict' — signalling that the result is judged by an exit code, but it never explains what that code means or what the plan output contains.

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 tight sentences with no filler, and the core scope statement is front-loaded. 'To its return point' is terse to the point of being obscure, but nothing is wasted.

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 and four parameters influencing the result (tier scaffolding, change profile, runtime resolution), the description should explain what a 'step' looks like and how the exit-code verdict is reported. Instead the agent is left to guess at the return shape and the meaning of 'return point'.

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 path, tier, change, and runtime are already documented in the schema, and the description does not elaborate on any of them. The baseline of 3 applies; 'for one file' only loosely restates the path parameter.

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 produced — an ordered implementation plan for one file — which is more specific than the bare name 'steps'. However it is a noun phrase with no explicit verb (generate? fetch? derive?) and gives no signal distinguishing it from siblings like route, mind_plan, or gate, so an agent must infer the operation.

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 statement of when to use this versus alternatives such as mind_plan, route, or gate, and no prerequisites or exclusions. The phrase 'to its return point' hints at scope but does not tell the agent under what conditions this tool is the right 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is redundant. The one genuinely additive phrase is 'the exit code is the verdict,' which hints the result carries a pass/fail determination, though it is unexplained for what is nominally a read of recorded successes. No disclosure of permissions, rate limits, or result shape, but with full annotation coverage the bar is lower.

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 tight sentences covering scope, parameters, and the read-only/verdict note — no filler. The front-loaded scoping clause is well placed, though the dense jargon makes the first reading slower than the length warrants.

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?

All three parameters are documented and annotations cover safety, but with no output schema the description should carry the burden of describing what is returned ('how each is proved' is asserted but never characterized). The concept of a 'move' and how proof is represented remain undefined, leaving a real gap for an agent interpreting results.

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

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

Schema description coverage is 100%, so the schema already defines `id`, `for`, and `limit`. The description echoes the schema's own mapping ('for' = file, 'id' = one move) rather than adding syntax, format, or interaction detail (e.g. what happens when both are supplied, or that `limit` only affects `for`). 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 gestures at a specific resource ('the moves that replaced recorded failures') and names the two scoping modes ('for' a file, 'id' for one move), but 'moves' is undefined domain jargon and the verb is only implied. An agent can guess this is a lookup of successful patterns, but it cannot confirm what a 'move' actually is or how it differs from the sibling `failures`/`proof` tools without opening them.

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 says which parameters scope the query but never states when to reach for this tool versus `failures`, `proof`, or `steps`. There are no exclusions, no prerequisites, and no mention of the sibling that is the obvious complement (failures), so the agent must infer the choice entirely.

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