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, and it delivers: it states the operation is read-only, explains the summary vs. full detail behavior, notes that sensitive files are summarized by default, clarifies that nothing is dropped in either mode, and specifies the failure behavior when no policy file exists. This is rich behavioral context beyond what any schema could convey.

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

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

The description is dense but every sentence earns its place: purpose, output format, usage timing, summary behavior, detail parameter semantics, and safety guarantee. It is front-loaded with the core purpose and ends with the most important safety and failure behaviors. 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 read-only audit tool with 2 optional parameters and no output schema, the description is complete. It covers what the tool returns, when to use it, how the parameters affect behavior, what happens in edge cases (no policy file), and the safety profile. An agent has everything needed to invoke it correctly without opening the schema.

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 adds value by explaining the practical effect of the detail parameter ('a 'nothing is due' answer stays small') and by clarifying that the full list is always written to report_path regardless of mode. It also explains the dupes parameter's cost ('slower'). This goes beyond the schema's descriptions.

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 ('Run a read-only workspace audit') and resource ('the metabolism policy'), and clearly distinguishes itself from siblings by emphasizing it returns a report and never modifies files. It also names the exact output (JSON report with paths, grades G1-G4, cleanup state, anomalies), which makes the tool's purpose unmistakable.

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

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

The description explicitly says when to use it: 'at the start of a session' and 'before planning any cleanup.' It also contrasts with the sibling wm_clean by stating it never moves or modifies files, which helps an agent choose between audit and cleanup tools. This is explicit when-to-use guidance with an implicit alternative.

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 fully discloses behavioral traits: dry-run default changes nothing, execution moves items to a recycle area rather than deleting by pattern, actions are hash-chained in a journal allowing rollback, and G3 execution requires approval. This is unusually transparent for a cleanup/mutation 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?

Four dense sentences, each earning its place: the main action, the default behavior and output, the safety properties, and the usage condition with warnings. It is front-loaded with the purpose and avoids 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?

Despite having no annotations and no output schema, the description covers what happens, what changes, what execution does, when it should be used, and the approval prerequisites. An agent has enough context to select and safely 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?

Since the schema covers all 5 parameters with descriptions, the baseline is 3. The description adds extra meaning by tying execute, approve, and approver to the G3 approval workflow and journal/rollback guarantees, and by clarifying that execute=false is a dry-run. It does not duplicate schema details unnecessarily.

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?

Opens with a specific verb and resource: 'Plan or execute a policy-driven cleanup' and immediately defines the dry-run vs execute modes. This makes it distinguishable from the sibling wm_audit/wm_rollback/wm_govern tools, which concern history, rollback, and governance decisions.

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?

States a clear trigger condition ('workspace has accumulated policy-expired byproducts') and gives explicit safety instructions: do not set execute=true without first running a dry-run, and G3 requires approve=true and an approver. It does not explicitly name sibling tools that should be used instead, but the use case is scoped well enough to route an agent.

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

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

With no annotations this description carries the full burden and does so: read-only semantics, the return shape (table names), explicit non-actions, failure semantics for missing/empty databases and missing required tables, and an explicit scope ceiling ('checks path/schema only, not data freshness or identity'). That last clause is exactly the kind of limitation an agent needs and cannot get from structured fields.

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?

Front-loaded identity statement followed by tightly packed scope, non-action, failure, and limitation clauses. No sentence is filler; each one carries distinct constraints.

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 and no annotations, yet the description covers return contents, failure modes, mutation guarantees, and the boundary of what success means. Nothing an agent needs to call this correctly is absent.

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 0%, so the description must compensate. It does add meaning by explaining that resource_id refers to a resource registered in the policy rather than an arbitrary file path, but it gives no format, example, or lookup behavior for the identifier. Minimal compensation over a single undocumented string 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?

States a specific verb (check) and resource (the exact SQLite resource registered by resource_id in the policy), and enumerates what the tool will NOT do, which cleanly separates it from siblings like wm_health, wm_verify, wm_audit, and wm_repair-style tools. An agent can pick this out without opening the schema.

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 negative list ('never creates databases or tables, repairs, deletes, searches for substitutes, or accepts SQL') gives clear boundary conditions that imply when this tool is the right choice, and the failure conditions tell the agent when it will error. It stops short of naming a concrete alternative sibling for the excluded operations, so it's clear context rather than full when/when-not routing.

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 present, the description carries the full behavioral burden, and it does so thoroughly. It explicitly labels the operation 'Read-only' and discloses the two error cases: paths outside the workspace and missing policy. It also describes the shape of the output (grade, reasoning, cleanup effect), giving the agent a solid expectation of what will come back.

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

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

Three sentences with no filler. The core function is front-loaded in the first sentence, the usage condition is second, and the read-only plus failure messages are third. Every sentence adds essential information and the description remains compact.

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, read-only explain tool with no output schema and no annotations, this description is fully sufficient. It covers what the tool does, what it returns, when to use it, that it is safe (read-only), and the failure modes. An agent has everything needed to decide when to call it and what to expect.

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 complete description of the single 'path' parameter, including its relative-to-workspace-root format and examples ('logs' or 'src/util.py'). The description adds no further parameter-level detail, but none is needed; per the calibration rule, baseline 3 is appropriate when schema coverage is 100%.

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

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

The description opens with a specific verb and resource: 'Return the nutrition label for one path', and goes on to enumerate exactly what the output contains (G1-G4 grade, rationale, cleanup effect). This clearly distinguishes it from the sibling tools: wm_clean acts on paths, wm_audit and wm_health operate at a broader level, whereas wm_explain is specifically about interrogating a single path. There is no ambiguity about what the tool does.

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

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

The second sentence explicitly states when to use it: 'Use this when you or the user ask why a specific file or directory is (or is not) cleanup-worthy.' This gives clear context for invoking it. It does not explicitly name a sibling as an alternative, but the provided sibling list and this conditional are enough to route an agent correctly without excluding anything.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does well by stating that the action is not performed, that unknown actions are denied by default, that write actions can require a preview, that sensitive actions can require an approver, and that the decision is recorded in a hash-chained journal. This provides meaningful behavioral context beyond the name and schema.

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

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

The description is compact and front-loaded. The first sentence states the core purpose immediately, and the following two sentences add essential behavior without fluff or repetition of schema field names.

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 governance semantics well but leaves important gaps for a tool with no output schema: it does not describe the shape of the result, what happens when preview or approver are actually needed, or how 'paths' factors into the decision. These missing details reduce an agent's ability to invoke the tool and interpret its response correctly.

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

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

Schema description coverage is only 25%, so the description needs to compensate. It adds meaning to 'preview' and 'approver' implicitly through the write-action and sensitive-action sentences, but it never explains the 'paths' parameter, which is a notable gap. The 'action' parameter is covered by 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 opens with a specific verb and resource: 'Check whether an AI action is allowed by the workspace policy'. It also clarifies that the tool does not perform the action, which clearly differentiates it from execution-type tools and from siblings like wm_audit, wm_explain, and wm_verify.

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 for when to use the tool: before an AI action, to check policy compliance. It also explains default behavior for unknown actions and special cases for write and sensitive actions. However, it does not explicitly state when NOT to use it or point to an alternative sibling tool for a given scenario.

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 states the tool is read-only, requires a policy file, and returns an error instructing the user to run 'wm init' if the file is missing. This is strong, specific behavioral transparency.

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

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

Three tightly written sentences communicate the computation, return format, use cases, read-only nature, prerequisite, and error behavior. Every sentence adds value, and the core purpose 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?

The tool is simple with no parameters, and the description covers both the return value and failure mode. Even without an output schema, the description tells an agent exactly what to expect and what conditions are required for successful invocation.

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

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

The tool has zero parameters and the schema reflects that with complete coverage, so there are no parameter semantics to clarify. The description adds useful output-field context by naming the breakdown components (coverage, compliance, cleanliness), which goes beyond the 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 states a specific action ('Compute the workspace health score') with a concrete output format ('0-100' score with per-component breakdown for coverage, compliance, and cleanliness). This clearly differentiates it from sibling tools like wm_verify or wm_audit by focusing on a single aggregate health metric.

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

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

The description provides explicit usage context: 'Use this to quantify in one number how well the workspace follows its policy, e.g. for CI gates or session-end reporting.' It gives clear scenarios for when to use the tool, though it does not explicitly mention when not to use it or name 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?

With no annotations provided, the description carries full behavioral burden and does so well. It discloses the scanning behavior, the safe-default grading policy, the never-auto-cleaned categories, the fail-without-writing behavior when a policy exists, and the destructive implication of force overwriting a hand-tuned policy.

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 focused sentences with no filler. The primary action is front-loaded, the scaffold analogy aids understanding, and edge cases around existing policies are compressed into one clear condition at the end.

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

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

For a tool with one optional boolean parameter and no output schema, the description is complete: it explains the purpose, the generated artifact, the safety profile, prerequisites, failure behavior, and when to set force. No critical information for correct invocation 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 lone parameter force is fully described in the input schema (100% coverage), including its default and effect. The description adds context about force replacing a hand-tuned policy, but since the schema already documents the semantics, additional value is marginal and 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 clearly states a specific action ('Scaffold the metabolism.json policy file') with an apt git init analogy, and names the resource (metabolism.json) plus the exact behavior (scan workspace, generate G1-G4 grades). It also differentiates itself from siblings like wm_audit and wm_clean by identifying init as the prerequisite step.

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?

Explicit usage guidance is provided: 'Use this once, when no policy file exists, before the first audit or clean.' It also states the failure mode when a policy already exists and clarifies when force should be used, leaving no ambiguity about the tool's place in the workflow.

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 behavioral burden and succeeds: it discloses integrity verification against SHA-256, skip conditions (integrity failure, missing items, overwrites) with reasons, dry-run behavior, and the failure message for an unknown run id. This goes beyond what a minimal description would include.

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?

Four sentences, each dense with relevant information and no filler. The purpose is front-loaded, followed by behavior, usage, and execution mode. Nothing can be removed without losing 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?

Given only 2 parameters, 100% schema coverage, and no output schema, the description covers what an agent needs to call the tool correctly: what it does, how to select the run, the dry-run safety default, the execute flag, potential skip reasons, and an error case. No critical gap is apparent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning beyond the schema by explaining that the run id is the one 'printed by wm_clean' and that execute=true 'actually restore[s]' rather than previewing. This contextual linkage is useful, though the schema already documents the parameters well.

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

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

The description opens with a specific action and object: 'Restore the items of a previous wm_clean run from the recycle area back to their original locations.' It clearly distinguishes this rollback operation from siblings like wm_clean, wm_audit, and wm_verify by naming wm_clean explicitly and explaining that this undoes a cleanup.

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 when-to-use guidance: 'Use this to undo a cleanup you just executed, passing the run id printed by wm_clean.' It also explains the execution model ('Dry-run by default; set execute=true to actually restore'), which tells the agent how to invoke it correctly and when to set the flag.

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 available, the description carries the full transparency burden. It explicitly states 'Read-only', describes the verification checks performed, and discloses the return format (JSON with pass/fail details). It omits error-handling or performance caveats, but for a zero-parameter read-only tool the disclosure is adequate.

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 purpose, followed by usage guidance and a read-only note. Every clause adds essential information 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?

The tool's complexity is very low (no params, no output schema), and the description covers what it does, what it returns, and when to use it. An agent has enough information to invoke and interpret the result 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 the schema coverage is 100%, so there is nothing for the description to add. The no-parameter nature is implicitly clear, and the baseline for tools with no parameters 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's action ('Verify the integrity of the audit trail') and the specific resources it checks (hash-chained journal, run manifests). It also describes the output as pass/fail JSON, which further distinguishes it from sibling tools like wm_health or wm_audit.

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 gives two concrete situations to use the tool: before trusting previous clean/rollback history or after suspecting manual edits to the journal. It does not name alternatives or exclusion cases, but the provided context is sufficient for most agent decision-making.

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