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

The description clearly discloses a side effect: 'Persists a measurement on every call' and implies cumulative behavior building a series. However, it does not mention whether the tool returns any output, whether it is idempotent, or other potential behaviors.

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

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

The description is extremely concise, consisting of two sentences. It front-loads the list of metrics and then states the persistent measurement behavior. There is no unnecessary verbiage.

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 explains the core behavior (persisting a measurement) but misses essential context such as what the output is (if any), what the measurement represents beyond the listed metrics, and any requirements or environment context. Given the simplicity, it is adequate but not fully 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 tool has no parameters; the schema is empty (properties: {}). Schema coverage is 100%, so the baseline is 3. The description adds nothing about parameters because there are none to explain, which is acceptable.

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 lists specific metrics (instance counts, detach rate, etc.) and states it persists a measurement, indicating it records adoption and health metrics, but it does not explicitly say 'records adoption metrics' or clearly define the primary action. It is inferential rather than a crisp verb+resource statement.

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

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

No guidance is provided on when to use this tool versus the many other tidy_* siblings. There is no context, example, or differentiation such as 'use this to record adoption metrics, use tidy_status to check current status.'

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

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

The description discloses key behavioral aspects: it is the only mutation tool, it refuses invalid plans, and on success it writes a decision entry. Since no annotations are provided, the description fully carries the burden of transparency, and it does so thoroughly.

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 succinct, with no redundant phrasing. It efficiently covers purpose, constraints, and side effects in three sentences, each contributing new information without 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?

It covers the tool's role, preconditions (plan from tidy_plan, valid hash), failure conditions (invalid, expired, changed targets), and postcondition (decision entry). Given the simplicity of the operation and lack of output schema, this is 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?

While the schema already describes each parameter, the tool description adds meaningful context: planHash is identified as coming from tidy_plan, confirm is framed as a deliberate second step, and note is implied to record reasoning. This enriches the parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: executing a plan identified by hash. It explicitly distinguishes itself as the only tool that changes anything in tidy-core, making its purpose unambiguous and differentiated from siblings.

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

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

It provides explicit usage conditions: it only executes plans generated by tidy_plan, and refuses expired plans or those with changed targets. This gives clear guidance on when and how to use it, and implicitly directs users to generate plans via tidy_plan first.

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?

There are no annotations, so the description carries the behavioral burden. It usefully discloses that the tool is '[NOT IMPLEMENTED YET]' and that results are ranked by impact over effort, not by count. However, it does not state whether the tool is read-only, what happens if invoked, or any side effects 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?

The description is a single sentence with no filler. It front-loads the critical implementation status, then lists the work categories, then explains the ranking rule. Every phrase earns its place.

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

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

For a zero-parameter tool with no output schema, the description conveys the core concept and categories, and it honestly signals that the tool is not ready. However, it leaves out what a worklist item actually looks like, how results are returned, and how this tool fits into the tidy_* workflow, which an agent would need if the tool were implemented.

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 there is no parameter documentation burden. The description instead orients the agent on the expected output content, which is the relevant semantic gap for a no-input tool. This matches the zero-parameter baseline.

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 deliverable: a ranked worklist of specific cleanup categories (ghost variables, dead styles, unused tokens, raw colors, deprecation candidates). It is not a tautology and gives concrete content, though it lacks an explicit verb like 'generates' or 'returns' and does not contrast itself with the many tidy_* siblings.

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

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

No guidance is given for when to use tidy_cleanup versus alternatives such as tidy_plan, tidy_apply, or tidy_health. The description implies it is for cleanup worklist generation, but it never states conditions, prerequisites, or exclusions, so an agent gets little help choosing among siblings.

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

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It communicates the return scope in detail and goes further by warning that not calling it leads to guessing, potentially causing 'raw hex' where components are affected. This gives an agent a strong sense of when and why the tool matters, even if it doesn't cover all edge cases like error handling or performance.

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 concise and well-structured. It opens with the core purpose, lists what's included, provides a direct instruction on when to call it, and closes with a rationale that motivates the action. Every word earns its place, and the most critical information is front-loaded.

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

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

For a read-only context-gathering tool with only optional parameters and no output schema, the description covers all essential information: what it returns, when to use it, and why it matters. It doesn't explicitly document default behavior for parameters, but the schema already handles that, making this description sufficient for an agent to decide when and why to invoke it.

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 describes all three parameters (detail, include, figmaFile) with enums and defaults, covering 100% of the information needed. The description adds no extra context about parameters, which is acceptable given the schema's completeness; the baseline of 3 is appropriate.

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

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

The description uses a specific verb in 'Get the design system contract' and enumerates the exact content: collections, modes, token names grouped by intent, component variant axes, and conventions. This makes it immediately differentiable from sibling tools like tidy_status or tidy_health, which likely address other aspects of the design system.

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 instructs to 'Call this before writing anything into the file,' giving clear usage context. It doesn't name alternative tools or provide when-not-to-use conditions, so it stops short of a 5, but the conditional guidance is strong and actionable.

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

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

The description marks the tool as read-only and includes a clear '[NOT IMPLEMENTED YET]' warning, which are useful behavioral signals. However, since there are no annotations, the description carries the full burden, and it does not disclose what happens if the tool is called despite being unimplemented or any other 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 concise and front-loads the critical '[NOT IMPLEMENTED YET]' warning. Each sentence adds value, though it could be slightly more structured. It is effective without being 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 zero-parameter tool, the description is reasonably complete: it states the operation and read-only nature. However, it lacks detail on the output format or behavior when called despite the not-implemented flag, which agents would need for safe interaction.

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 there is no parameter schema to document. The description still explains what the tool does operationally, which is sufficient. With no params, a baseline of 4 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: to search the decision record, find components lacking rationale, and detect contradictions. It uses specific verbs and distinct outcomes. It does not explicitly name a sibling, but the purpose is distinct from the other tidy_* 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 when to use this tool (for auditing decisions) but does not explicitly state when not to use it or name alternatives among the many tidy_* siblings. Given the large family of tools, this is a gap.

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

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

The description offers no insight into side effects, permissions, rate limits, or any behavioral traits. The '[NOT IMPLEMENTED YET]' label suggests it currently does nothing, but this is not explained, and no annotations exist to fill the gap.

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 brief, but it is unstructured and ambiguous. It mixes a status note with an incomplete product description, and the sentence is not sufficiently informative to be considered well-crafted.

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 fundamentally incomplete—it announces an unimplemented feature but does not explain what the report would contain, how to interpret it, or how to invoke the tool. Without any output schema or additional context, an agent cannot determine what this tool does or if it is usable.

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 has zero parameters, so there is no additional information to add. The description does not clarify any implicit arguments (e.g., which surfaces to target), but with no parameters defined, the baseline of 3 is appropriate.

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

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

The description states the tool produces a 'drift report' across four surfaces, but it does not clearly define the action (e.g., generate, compare, analyze). The phrase '[NOT IMPLEMENTED YET]' further obscures any intended functionality, leaving the tool's purpose vague.

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 or how it relates to sibling tools like tidy_status or tidy_plan. There is no mention of conditions, alternatives, or prerequisites, making it impossible to determine appropriate usage.

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, and it prominently warns '[NOT IMPLEMENTED YET]', which is critical behavioral information. It also discloses the checks performed and the outcome behavior ('passes or fails with reasons'). It does not mention side effects or whether any state is modified, but as a verdict tool that is a minor gap.

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

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

The description is compact, front-loads the essential 'NOT IMPLEMENTED YET' warning, and packs the tool's purpose, checks, and outcome into one efficient sentence. Every word contributes meaning and 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?

For a zero-parameter, no-output-schema tool with no annotations, the description covers the main use context, the included checks, and the pass/fail result. It could be more explicit about the exact return format or how 'reasons' are presented, but 'passes or fails with reasons' is sufficient for an agent deciding whether and how to invoke it.

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 no-parameter baseline applies and there is nothing for the description to elaborate on. The description's mention of the checks run adds context without needing to explain parameter syntax or formats.

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

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

The description opens with 'CI and pre-push verdict', making the tool's role immediately clear, then enumerates the specific checks it runs: drift, cleanup regressions, publish readiness, and decision compliance. It stops short of a 5 because it does not explicitly distinguish itself from sibling tools like tidy_drift or tidy_cleanup, though the aggregate nature is strongly implied.

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?

'CI and pre-push verdict' provides a clear context for when the tool should be considered, and the listed checks signal that this is an aggregate gate rather than a single-purpose diagnostic. It does not explicitly say when not to use it or name alternative tools, so it lacks the explicit routing needed for a 5.

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 bears the full burden. It discloses a key behavioral trait: it persists a snapshot on every call, which implies statefulness and potential side effects (mutating stored data). However, it does not disclose whether this persistence is destructive or could overwrite previous snapshots, nor does it specify any requirements or limitations (e.g., no snapshot exists on first call, so delta is null). The disclosure of persistence is useful but incomplete.

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 concise and front-loaded with the main output (six-category score), followed by the delta and cause. The single sentence conveys everything without fluff. It loses a point because the '[NOT IMPLEMENTED YET]' prefix is a temporary placeholder that could be removed once the tool is ready, slightly cluttering the description.

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 has no parameters, no output schema, and no annotations, so the description is the sole source of context. It covers what the tool returns (score, delta, cause) and a key side effect (persists snapshot). It lacks details on the return format (e.g., structure of cause, maybe a list of factors), but given zero params and no schema, this is a minor gap. The description is complete enough for an agent to invoke it correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameters to document. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than parameters. No improvement is needed here.

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 function: it computes a six-category health score, provides the delta since the last snapshot, and explains the cause of the delta. This is a specific verb (computes/provides) plus a clear resource (health score), and it distinguishes itself from siblings like tidy_status by emphasizing the delta and causation.

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 through the delta mechanism ('second run has a delta'), but it does not explicitly state when to use this tool over siblings like tidy_status or tidy_drift. There is no explicit when-not guidance. It provides a clear core scenario but leaves alternative routing to the agent's inference.

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

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

With no annotations, the description carries the full burden. It does disclose read-only behavior and the 'NOT IMPLEMENTED YET' status, plus the general shape of results. However, it omits how the target is selected, any prerequisites, error behavior, or what 'read-only' means exactly in this toolset.

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 sentences with no filler. The 'NOT IMPLEMENTED YET' warning is front-loaded, and each sentence contributes either scope, expected output, or safety behavior.

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 an unimplemented, parameterless tool, the description conveys intent and safety adequately. But it leaves uncertainty about invocation: no input schema, no mention of relying on a current session target/context, and no output schema. An agent could understand what the tool would eventually do but not how it would be called.

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 has zero parameters, so the baseline is 4. The description adds meaningful context by naming the subject categories (token, component, style) and the evaluation dimensions (breakage, migration costs, regression risk), but it does not clarify how the subject is supplied given the empty input schema.

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

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

The description clearly states the tool's domain: blast radius for a token, component, or style, and enumerates the expected outputs: breakage, migration costs, and regression risk. It is distinct from sibling tools like tidy_status or tidy_plan, but it uses a noun phrase ('Blast radius for...') rather than a direct action verb and does not explicitly name a sibling contrast.

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 versus alternatives like tidy_plan, tidy_apply, or tidy_drift. The phrase 'What breaks if you rename it' implies a rename-impact scenario, but no conditions, exclusions, or sibling routing 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?

With no annotations provided, the description carries the full burden and does so excellently. It discloses that the tool never mutates anything, reports dependencies and risks, and refuses to issue a hash when an operation would break something. This gives a clear behavioral model without contradicting any structured metadata.

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 sentences with no filler: it front-loads the primary purpose, then safety and failure behavior, then the critical pairing with tidy_apply. Every sentence adds value and supports correct invocation.

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 planning tool with three operation variants and no output schema, the description covers the essential context: non-mutating behavior, dependency/risk reporting, hash refusal on breakage, and which sibling executes the plan. It is fully adequate for an agent to decide when and how to call it.

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 parameters are fully documented in the input schema with descriptions for operations, intent, and figmaFile. The tool description adds general context about planning but does not add detailed parameter-level meaning beyond what the schema already provides. 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 clear action ('Build a reviewable plan') and a concrete output ('return a hash'), distinguishing it from the sibling tidy_apply, which is explicitly named as the executor. There is no ambiguity about what tidy_plan does.

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

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

The description gives clear context: use it to build a reviewable plan before executing, and pair it with tidy_apply, the only tool that can execute the plan. It does not explicitly list exclusions against other siblings like tidy_status, but the planning-vs-execution distinction is strong enough for an agent to route 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 must carry the transparency burden. It mentions 'Record' implying a write operation, but does not disclose any side effects, permissions, or storage location. The note 'NOT IMPLEMENTED YET' is a state disclosure but not about runtime 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 concise, with two sentences that convey the purpose and usage without extraneous detail. It is well-structured and easily parsed.

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 absence of output schema and annotations, the description provides moderate context: it explains what the tool does and when to use it. However, it omits any mention of return values or side effects, and the placeholder status ('NOT IMPLEMENTED YET') leaves some ambiguity about expected 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?

The input schema shows zero parameters, which matches the lack of parameter information in the description. Since there are no parameters to explain, the description does not need to elaborate, but it also doesn't mention that the tool takes no arguments, which could be a minor 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 clearly states the tool's purpose: to record why a change was made. The verb 'Record' and resource 'change reason' are specific, and the note about being called by tidy_apply provides some differentiation, though it doesn't explicitly name alternative tools for comparison.

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 explicit usage context: called automatically by tidy_apply and manually for decisions made in meetings. This implies it should not be used for changes already captured in diffs, providing an implicit when-not-to-use condition.

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 output includes a `routing` field, explains its meaning, and reveals that when 'nothing is connected' it returns concrete fixes rather than just a boolean. This goes beyond the minimal schema and gives the agent actionable expectations about the tool's 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?

Three concise sentences with the primary purpose front-loaded. Every sentence adds value: the first defines what it does, the second instructs on how to interpret output, and the third discloses behavior in the failure case. 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?

For a zero-parameter status tool, the description adequately explains what it returns and how to interpret it. It mentions the `routing` field and the fallback behavior when nothing is connected. It doesn't describe the exact output schema, but that's acceptable per the rubric since no output schema exists. The only minor gap is not listing what the concrete fixes might look like, but that's beyond the scope for a concise status check.

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 per the guidelines the baseline is 4. The description correctly focuses on the tool's output and behavior rather than parameters, which is entirely appropriate given the schema is empty.

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: 'Check where tidy-core is connected and where the next command will land.' It specifies the resource (tidy-core), the action (check status), and the key concept (routing). It also differentiates from siblings by explaining the routing field, which is unique to this tool among the listed siblings.

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

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

The description gives context on what to do ('Read the `routing` field first') but does not explicitly state when to use this tool versus alternatives like tidy_target or tidy_plan. Given it is a status-check tool, the use case is implied, but there's no explicit guidance on exclusions or 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 clearly discloses that the tool mutates state (pins/unpins), that calling with no arguments is a read operation, and that absence of a target causes failure with a list rather than guessing. This is a good disclosure of edge-case behavior and safety concerns (avoiding writing to wrong file). The description doesn't mention persistence or scope (e.g., session vs persistent), but that's minor. 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 concise and front-loaded: the primary action ('Pin every subsequent command') is first, then accepted inputs, then edge-case behaviors. Every sentence earns its place—no filler or repetition. It's appropriately sized for a tool with two optional parameters.

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

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

The tool is simple (0 required params, no output schema, no nested objects), yet the description covers all necessary behavioral aspects: how to set, view, clear, and the failure mode when ambiguous. It even explains a design rationale (avoid guessing). Given the low complexity, this is complete. An agent has enough info to call it correctly in all scenarios.

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 documented. The description adds value beyond the schema by explaining the exact matching behavior ('Names match exactly first, then case-insensitively') and the effect of clear: true. It also clarifies that file can be a name or key, which the schema doesn't explicitly state. Since the schema already covers basics, the description enriches semantics meaningfully.

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 pins subsequent commands to a connected Figma file, accepts a file name or key, and lists specific behaviors like calling with no arguments to see the current target or clear: true to unpin. This distinguishes it from siblings like tidy_status or tidy_context which likely query state rather than set a target.

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 explains when to use the tool (to set or view the target), and provides a critical usage note: if multiple files are connected and no target is set, commands fail with a list of files rather than guessing. It doesn't explicitly mention when not to use it or alternatives, but the context signals for siblings suggest it's the only pinning tool. A slight gap is not listing alternatives when the user wants a different operation like checking status, but that is implied by sibling names.

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