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

The annotations declare destructiveHint=true, but the description does not disclose what is destructive: it never says whether 'start' overwrites an existing brainstorm document, where the file is written, or whether content is appended versus replaced. For a destructive-flagged write tool with no output schema, this is a meaningful 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the under-specification noted elsewhere rather than being a virtue on its own.

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 four parameters, a destructive annotation, and no output schema, the description omits the file-writing behavior, overwrite semantics, and project auto-detection. An agent cannot fully predict the side effects of calling 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 description coverage is 100%, so the schema already documents all four parameters (topic as filename, content, auto-detected project slug, workspace_path constraint). The description adds no syntax or format 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?

States a specific verb (start/continue) and resource (brainstorm document) scoped to a project, so an agent can tell it apart from generic siblings like 'write' or 'template'. However, it does not explicitly differentiate itself from those siblings, which keeps it below a 5.

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

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

There is no guidance on when to use this tool versus siblings such as 'write', 'template', or 'capture', and no exclusions or prerequisites. The implied usage (capturing brainstorming) is left entirely to inference.

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

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

Annotations already flag destructiveHint=true. The description adds real value beyond that by disclosing per-item file creation and auto-numbering, which tells the agent this fans out into many artifacts. It does not say whether items overwrite existing files, what happens on partial failure, or what is returned.

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 compact sentences with the core action front-loaded and no filler. Slightly more could be trimmed by folding the content-type list, but every sentence carries information.

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

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

With 100% schema coverage and no output schema, the description covers the action and its file-per-item effect. It is still thin for a destructive-flagged batch mutation: no return shape, no failure or duplicate-handling behavior, and no note on the workspace_path/project coupling described in 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 every parameter (items, project, workspace_path, and nested item fields) is already documented in the schema. The description only restates the content-type flexibility, adding no syntax, defaults, or constraints beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Batch-capture multiple insights from a conversation into individual vault items.' The batching and one-file-per-item outcome are clear. However, it never distinguishes itself from close siblings like learn, write, extract, or decide, so an agent must infer which one applies.

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?

'From a conversation' and 'batch' imply the usage context, and the enumerated content types signal breadth. But there is no explicit when-to-use guidance versus learn/write/decide, and no exclusions or prerequisites (e.g. when not to batch).

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?

Goes beyond the readOnlyHint annotation by disclosing the tri-state verdict (verified|refuted|unverifiable), that results carry node ids and edge confidence, and the crucial constraint that hard verdicts require EXTRACTED facts. This is genuine behavioral context, though nothing is said about determinism guarantees across re-scans 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?

Two dense sentences, front-loaded with the core action before the kind list, and the return-value sentence earns its place. The kind enumeration is long but necessary given six variants.

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 carries the return contract and it does: verdict vocabulary, node ids, edge confidence, and the EXTRACTED-facts requirement. Combined with 100% schema coverage on inputs, an agent has enough to call this 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 coverage is 100%, so baseline is 3, but the description adds real value by mapping each claim kind to its required fields (e.g., file-exists {path}, import-resolves {from,specifier}), telling the agent which payload shape to build per kind — information the schema only implies field-by-field.

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+resource: 'Verify structured claims against a deterministic code-graph scan of a root'. The kind enumeration further pins down exactly what can be verified, distinguishing it from generic scan/graph tools among the 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?

Usage is implied by 'verify structured claims' but the description never states when to prefer this over siblings like graph_related, graph_traverse, or evidence, nor any prerequisites or exclusions. Adequate but leaves routing to inference.

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

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

The only annotation is destructiveHint=true, and the description never addresses write/overwrite behavior, permissions, or what the add vs list actions do. It does add useful context that credentials themselves are not stored, which is a meaningful behavioral clarification given the sparse annotation.

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, front-loaded with the core purpose and followed by a concrete example. No waste; the example earns its place by clarifying the 'pointer' concept.

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 only a destructiveHint annotation, the description carries more burden than it fills: it never mentions the add/list action enum or what listing returns. For a dual-action tool with sparse annotations, this is adequate but incomplete.

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 six parameters including name, location, and action. The description's example indirectly illustrates name/location but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description gives a specific verb+resource: storing pointers to where credentials are documented, and explicitly carves out scope via '(not the credentials themselves)'. It is unambiguous, though it does not name any sibling to differentiate from, likely because none compete.

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 through the example ('Django admin creds are in tests/...'), which signals the intent to record references rather than secrets. There is no explicit when-to-use, when-not, or alternative tool named, leaving routing to inference.

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

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

Annotations supply only destructiveHint=true, leaving the description to explain the write behavior, and it does not: it never says whether an existing decision is overwritten, appended, or versioned, what file format is produced, or what makes the operation 'destructive'. Only the storage location is disclosed, so a meaningful behavioral gap remains for a 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?

A single front-loaded sentence with no filler, which is efficient. Given a seven-parameter mutation tool, however, the extreme brevity arguably under-serves rather than optimizes.

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 seven parameters, no output schema, and only a single annotation hint, the description should carry more weight. It omits the decision-record format, the relationship between 'project' and 'workspace_path', and the result of the call, leaving an agent to infer the contract.

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

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

Schema description coverage is 100%, so all seven parameters (title, context, decision, alternatives, consequences, project, workspace_path) are already documented in the schema. The description adds no syntax, format, or constraint details beyond that, which matches the baseline 3.

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

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

The description names a specific verb ('Log') and resource ('architectural/design decision') plus the destination ('project's decisions directory'), which is concrete enough to act on. It does not, however, distinguish this from plausible siblings like 'capture', 'learn', 'spec', or 'evidence', which also record project artifacts.

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 tool versus the many other recording tools ('spec', 'tickets', 'evidence', 'capture', 'learn', 'brainstorm'). The only guidance is implicit in the word 'decision'.

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 destructiveHint=true annotation already signals a mutation. The description adds useful context by clarifying that the action is marking as deprecated rather than deleting, and that a reason is optional, but it does not cover auth, reversibility, or side effects.

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

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

The description is a single front-loaded sentence that names the action, resource, and optional parameter without waste. Every clause earns its place.

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

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

For a low-complexity mutation tool with full schema coverage and a destructiveHint annotation, the description is largely complete. It could do more to clarify behavior around sibling tools and workspace_path, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already defines path, reason, and workspace_path. The description repeats that reason is optional but adds no syntax, constraints, or meaning beyond what the schema provides.

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 verb and resource: mark a vault item as deprecated, with examples of item types. It does not explicitly differentiate from siblings such as prune or other mutation tools, so it stops short of a 5.

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

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

The description gives no explicit context about when to use this tool versus alternatives like prune. It implies usage from the purpose alone, but there is no when-to-use or when-not-to-use guidance.

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

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

readOnlyHint=true already declares this is a safe, non-mutating operation, and the 'health check' framing is consistent with that. The description usefully signals breadth (it inspects install-vs-running state and flags graph isolation), but adds nothing about permissions, runtime cost, or how results should be interpreted beyond what the enumeration implies.

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 the core purpose stated first, followed by a compact list of checked domains. It is dense but every listed item maps to a real sub-check; no padding beyond the slightly run-on enumeration.

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 diagnostic with no output schema and one optional parameter, enumerating the inspected domains gives an agent enough to decide when to invoke it and what to expect it to examine. Return format is undocumented, but that is largely covered by the absent output 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 coverage is 100% and the single 'fast' parameter is fully documented in the schema (skip catalog validation and toolchain probes). The description does not reference the parameter at all, so the schema carries the entire burden; baseline 3 applies.

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

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

States a specific purpose (a one-shot health check) and enumerates the exact domains it inspects: MCP servers, vault/project mapping, graph isolation, rules catalog, toolchains, telemetry, and clients. This lets an agent know it is a broad diagnostic sweep, but it never distinguishes itself from overlapping siblings like status, hygiene_report, or watchdog.

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

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

No when-to-use guidance is given; 'one-shot' implies a single comprehensive run but there is no stated condition for choosing this over status/hygiene_report. No exclusions or prerequisites are mentioned, leaving routing entirely to inference.

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered, and the description sensibly adds that secrets must not go here. But it never says whether an 'add' overwrites an existing key, whether facts persist across sessions, or what 'auto-detected' project resolution means in practice, which matters for a write-capable 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?

Two sentences, front-loaded with the core capability and immediately followed by the exclusion rule. No filler, no restatement of the name, every clause carries information.

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

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

For a 6-parameter, write-capable tool with no output schema, the description covers the what and the secrets boundary but omits return/listing behavior and the semantics of repeated adds. Adequate to call correctly, but not complete.

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

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

Schema description coverage is 100%, so key, value, context, project, workspace_path, and the action enum are all documented in the schema itself. The description only reinforces the value domain (auth backend, env vars, URLs) without adding format, validation, or defaulting detail, so it meets the baseline but not more.

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 specific verbs (store and query) applied to a specific resource (stable environment facts for a project), and the parenthetical examples (auth backend, env file locations, local URLs, required env vars) make the scope concrete. It also names the adjacent-but-different sibling cred_refs so the agent can separate the two without reading schemas.

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?

Explicitly carves out the boundary case: 'Not for secrets — use cred_refs for that.' That is a genuine when-not rule with a named alternative. It does not, however, describe when to prefer env_facts over project_context, learn, or register, some of which store project-level knowledge, leaving the broader routing implicit.

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

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

Beyond the destructiveHint annotation, the description discloses where data lands (projects/<slug>/evidence/<ticket>.jsonl) and what is stored (command, exit code, truncated output, commit, timestamp), including the append semantics. It doesn't explain how the destructiveHint interacts with an append-only model or mention workspace_path mapping requirements, but the storage behavior is well conveyed.

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

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

Two tight sentences, front-loading the purpose and available actions before the storage detail. Nothing is wasteful, though the second sentence is information-dense and could be slightly more scannable.

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 11-parameter tool with no output schema, the description covers purpose, actions, and storage adequately, but leaves gaps around the workspace_path mapping constraint and how list results are shaped. It is minimum-viable rather than fully complete.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in the schema. The description mentions the stored fields but adds no syntax, defaults, or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource pair ('Record and read ticket evidence') and enumerates the two actions (add, list), so the agent knows exactly what it does. It doesn't differentiate itself from siblings like tickets or spec, but the resource is distinctive enough that confusion is unlikely.

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?

Lists the actions but gives no guidance on when to record evidence versus when to read it, nor when to prefer this over sibling tools like tickets or capture. Usage is entirely implicit.

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

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

Annotations only declare destructiveHint=true, so the description usefully adds that output is one file per item with a backlink to the source. However it never explains what is destructive about the operation (e.g. overwriting existing files or mutating the source), leaving the flagged risk unexplained. Some added context, but a notable 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?

Two tight sentences, purpose front-loaded, and the second sentence carries genuine output-structure information rather than padding. No waste.

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

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

For a 4-param mutation tool with destructiveHint and no output schema, the description covers purpose and output shape but omits what destructive behavior to expect and what the call returns (counts, paths). Complete enough to attempt the call, but leaves the risk profile and return unaddressed.

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 source, items, project, and workspace_path. The description only maps loosely to 'source document' and output files, adding no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 for high 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?

States a specific verb (extract) and resource (decisions, learnings, items) plus the output shape (individual vault files with a backlink). An agent can tell it transforms one source note into many item files, distinct from single-item siblings like decide or learn. It doesn't explicitly name the alternatives it competes with, so it stops short of 5.

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

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

The description says what happens but never when to choose extract over decide, learn, or capture, nor any prerequisite such as needing a source note to exist. No exclusions or trigger conditions are given.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description is not burdened with safety disclosure. It still adds value by disclosing that the check is deterministic, that it validates hash integrity and HEAD-pinned evidence, and that it returns pass/fail plus the missing items – a behavior an agent could not infer from annotations or 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?

Two dense sentences with zero filler: the identity/guarantee first, the checked conditions second, and the return shape last. Every clause earns its place.

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

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

With no output schema, the description correctly carries the return contract ('pass/fail with the missing items'), and annotations cover safety. It leaves minor gaps – error behavior for an unknown target or how spec vs ticket mode is disambiguated – but is largely complete for a read-only validation tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the NNN/slug/path and ticket-NNN formats. The description touches on 'HEAD' and 'evidence' concepts that loosely correspond to the head/cwd parameters but adds no format or override semantics beyond the schema, so the baseline 3 applies.

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

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

States a concrete verb and resource ('Deterministic evidence gate') and enumerates exactly what is checked for each of the two target types (spec: fields complete, frozen, hash intact; ticket: acceptance, frozen spec, evidence at HEAD, review evidence). This is far more specific than the sibling tools spec/tickets/evidence, which are storage-oriented rather than validation-oriented.

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 two target types imply when the tool applies, but there is no explicit when-to-use/when-not statement and no reference to alternatives such as running the check manually via spec/tickets/evidence. Usage is implied by the target enumeration rather than 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?

Beyond the readOnlyHint annotation, the description explains that it returns a draft and that human review is required before committing, clarifying the tool's non-persistent behavior. It does not contradict the annotation.

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

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

The description is a single sentence of 19 words, front-loaded with the primary action ('Scan'), and every phrase contributes meaningful information with 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?

For a read-only draft generator with two parameters and a simple response, the description covers the core behavior, return value, and key constraint (no writing to vault). The absence of an output schema is mitigated by the clear statement that it returns a draft.

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 both parameters, so the schema already documents slug and project_path adequately. The description adds no additional parameter semantics, making a baseline score of 3 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 scans a git repo and generates a draft context.md, with a specific verb and resource. It distinguishes itself from write tools by explicitly noting it does NOT write to the vault.

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

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

The description implies usage for drafting context that requires human review and explicitly notes it does not write to the vault, but it does not name specific alternatives or provide explicit when-to-use/when-not-to-use guidance.

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

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

Annotations cover the read-only safety profile. The description adds the meaningful behavioral constraint that scope is limited to the current project and cross-project access fails, which is useful beyond the annotation. However it says nothing about failure modes (does denial raise an error?), result shape, or pagination.

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, zero filler, and the scope restriction is front-loaded before the denial clause. Efficient, though the brevity is arguably under-specification rather than tight editing.

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 three-parameter read-only search with no output schema, the description covers the critical scope rule but omits error behavior on denial and any relation to the graph_related/graph_traverse siblings. Minimum viable but with clear gaps.

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 limit, query, and workspace_path all documented including defaults, bounds, and the cwd caveat. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (search) and a precise resource scope (the current project's vault only), and immediately negates the cross-project behavior implied by the name. The name 'graph_cross_project' is misleading against the actual restriction, but the description corrects it cleanly. No explicit differentiation from graph_related or graph_traverse.

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?

'Cross-project search is denied' conveys a boundary condition, but only implicitly tells the agent when this tool applies. It never names graph_related or graph_traverse as alternatives or explains when to prefer this search over them, so usage is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the underlying data sources (frontmatter + wikilinks) and the project-jailing constraint. It does not describe the shape or ordering of results, so it stops short of rich behavioral 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?

A single tight sentence with the core purpose front-loaded and a parenthetical that earns its place by naming the index sources. No filler, though the parenthetical is jargon-dense.

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 lookup with full schema coverage and no output schema, the description supplies the mechanism and scope an agent needs to choose it correctly. The only gap is that it never says what the call returns (e.g., a list of related note paths), which would help against the output-schema-less surface.

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 hops, path, and workspace_path, including the hops range. The description adds no numbering, default, or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific resource (related notes) and the mechanism (FTS/edge index built from related frontmatter + wikilinks), which is more than a tautology. The 'jailed to this project' clause implicitly distinguishes it from graph_cross_project, though it doesn't name the sibling outright.

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 'jailed to this project' scope implies when this is appropriate versus the cross-project sibling, but there is no explicit when-to-use statement, no exclusion, and no named alternative such as graph_traverse. Usage must be inferred.

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 only supply readOnlyHint=true, so the description carries the rest. It usefully discloses that traversal happens 'without loading bodies' and that open output is capped at 4096 UTF-8 bytes by default, which is meaningful behavioral context. It stops short of noting pagination behavior, permissions, or rate limits.

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 dense sentence, front-loaded with the core operation and then the per-action breakdown. Efficient, though the semicolon-separated clause list is slightly compressed and could be easier to scan.

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 usefully characterizes return values per action (metadata, size estimates, file/symbol spans). Combined with the readOnly annotation this covers the essentials; only pagination and cross-tool routing are unaddressed.

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 8 parameters with their per-action requirements and defaults. The description reinforces some of this (byte cap, size estimates) but adds little beyond what the schema already states, making the baseline 3 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?

States a specific verb (traverse) and resource (project index) and enumerates the four action modes with their outputs. It distinguishes the actions from each other, though it does not explicitly differentiate itself from siblings like graph_related or search.

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 action breakdown implies when each mode applies (metadata vs. relevance resolution vs. file retrieval), giving implied usage. However, there is no explicit guidance on choosing this tool over graph_related, graph_cross_project, or search, nor any exclusions.

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

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

readOnlyHint=true already establishes the safety profile, and the description reinforces it with 'Read-only' and 'deletes nothing'. It adds real context beyond the annotation: the report spans mapped repos, flags DUE entries with reasons, and surfaces exact remediation commands. No output schema exists, so this return-shape detail is genuinely valuable.

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

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

Two sentences, zero filler, scope and category list front-loaded, and the non-destructive guarantee placed last where it matters most. Every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does so well: it explains that entries are marked DUE with reasons and remediation commands. Minor gaps remain around cost/pagination behavior (the schema hints 'sizes' is slower) and how repos are discovered, keeping it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, and the description largely restates them by naming the category set. It adds only marginal meaning (machine-wide scope, repo mapping requirement) beyond what the schema 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?

States a specific verb (report) and resource (machine-wide space hygiene across mapped repos) and enumerates the exact categories covered: build caches, git worktrees, docker, xcode, agent scratch. The closing 'Reports only — deletes nothing' separates it cleanly from destructive siblings like worktree_gc or prune.

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 'Reports only — deletes nothing' framing makes the use case clear (inspect before cleaning) and implicitly contrasts with deletion-oriented siblings. It never names a specific alternative tool (e.g. worktree_gc) or states when *not* to use it, so it stops short of 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?

Read-only is already covered by readOnlyHint=true, but the description adds real behavioral context beyond the annotation: it is deterministic and LLM-free, and it distinguishes EXTRACTED results (definitions, importers) from INFERRED ones (callers), signaling differing confidence levels. It does not address cost, limits, or failure modes, keeping it short of a 5.

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 dense sentence that front-loads the core verb and resource, then lists the return categories and the read-only guarantee. No filler, no restated name, every clause carries information.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so by naming the four result categories and the optional path output. Read-only behavior is also stated. It stops short of describing result limits, graph staleness, or empty-result behavior, which a graph analysis tool would benefit from.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description confirms the dual-target behavior ('shortest graph path to a second target') and the file-or-symbol nature of target, matching the schema without adding syntax, format, or default guidance beyond it. Baseline 3 for a fully covered 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?

States a specific verb and resource: deterministic code-graph impact analysis for a file or symbol, and enumerates what it returns (definitions, importers, callers, shortest path). It implicitly differentiates from graph_related/graph_traverse by framing the tool around change impact, but never names those siblings, so an agent must infer the boundary.

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

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

Usage is implied by the name and framing ('impact', 'no LLM'), suggesting it fits when you want deterministic blast-radius answers rather than LLM-generated ones. However, there is no explicit when-to-use statement and no mention of the sibling graph tools (graph_related, graph_traverse, extract) that an agent would otherwise have to choose between.

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?

destructiveHint=true is declared, and the description does add useful operational context (it indexes, builds a graph, and registers the repo — all non-trivial side effects). However, it never explains WHY the operation is destructive or what existing state it overwrites, so the destructive annotation is left unelaborated.

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 with the primary action, followed by a compact comma-list of steps and a one-clause exclusion. Minimal waste, though the step enumeration is slightly dense for a single sentence.

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 setup/mutation tool with no output schema, the description covers what it does and its scope boundary well. Its main gap is not clarifying the destructive nature flagged by annotations, but otherwise an agent has enough 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?

Schema description coverage is 100%, so slug and bridge are already fully documented in the schema. The description adds nothing about either parameter, so the baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Initialize) and resource (superskill for the current project), then enumerates the concrete operations: stack detection, catalog indexing, knowledge-graph build, vault registration. The negative scope ("Does not scrape skills.sh") further bounds it, though it doesn't name a specific sibling alternative for 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?

The phrase "for the current project" and "auto-detection" imply this is first-time project setup, but there is no explicit when-to-use, no prerequisites, and no comparison against siblings like knowledge_rebuild or register. Usage context is only inferred.

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 only declare destructiveHint=false; the description adds the genuinely useful trait that the index is derived and the markdown files remain the source of truth, so a rebuild cannot lose content. It stops short of disclosing duration, cost, or what happens on partial failure.

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

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

Two sentences, no filler, and the core action is front-loaded before the safety note. Every clause earns its place.

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

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

For a two-parameter maintenance tool with no output schema, the description covers what it does and the key safety guarantee, but omits the operational context an agent needs: when to invoke it, expected runtime, and whether the index is usable during/after the rebuild.

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 (project slug, workspace_path) are already documented in the schema, including auto-detection and the cwd fallback. The description adds nothing parameter-specific, so baseline 3 applies.

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

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

Specific verb ('Rebuild') plus a precisely named resource ('SQLite FTS5 + edges index from markdown') — an agent knows exactly what artifact is produced and from what input. It does not, however, name or distinguish itself from index-adjacent siblings like knowledge_viz, link, extract, or graph_related.

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 run this versus alternatives (e.g. after markdown edits, or instead of re-running 'link'/'extract'). The reader must infer that a stale index is the trigger. No prerequisites or exclusions are given.

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 annotation declares destructiveHint=false, covering the safety baseline. The description contributes useful extra context that the tool also rebuilds the project index as a side effect and emits Obsidian-native markdown. It still omits whether existing notes are overwritten or merged, and whether the index rebuild is conditional or guaranteed.

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

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

A single compact sentence that front-loads the primary write action and appends the index-rebuild side effect. No filler, though it is dense enough to blur the two distinct operations.

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 write/mutation tool with only a destructiveHint annotation and no output schema, the description should clarify persistence semantics (overwrite vs append), permission needs, and the relationship to knowledge_rebuild. None of that is present, leaving meaningful gaps for a mutating operation.

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

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

Schema description coverage is 100% and both optional parameters (project auto-detection, workspace_path constraint) are fully documented in the schema. The description adds nothing beyond that, 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 states concrete actions — writing architecture/code notes in Obsidian markdown and rebuilding the project index. However, the name 'knowledge_viz' implies visualization and is not reconciled with the actual write behavior, and the sibling 'knowledge_rebuild' overlaps on index rebuilding without any differentiation.

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

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

No when-to-use or when-not-to-use guidance is given. It does not explain when to pick this over the sibling 'knowledge_rebuild' (which also rebuilds an index) or over 'write'/'capture' for persisting notes.

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 destructiveHint=true annotation is not contradicted; the description corroborates that this tool writes state by stating learnings are 'stored as individual files in projects/<slug>/learnings/'. It adds the persistence model and storage location beyond the annotation, but says nothing about reversibility, permissions, or how add vs list differ behaviorally.

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 compact sentences with the core purpose front-loaded and no filler. The final storage-path sentence is slightly more implementation detail than selection aid, which keeps it short of a 5.

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 11-parameter tool with only one required field and no output schema, the description is thin: it does not explain the two action modes ('add' vs 'list'), what add persists, or what list returns. The schema covers parameters, but behavioral completeness for a multi-action tool is only partially met.

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 11 parameters, including the action enum and requireds for add. The description adds no parameter-level detail (e.g. how tag differs from tags, or what the action values return), 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 specific verbs and a resource: 'Capture and query learnings', and adds scope with 'persist discoveries across sessions' and the storage location. It is clear what the tool does, but it never distinguishes itself from plausible siblings such as capture, decide, knowledge_rebuild, or search, so an agent must infer the boundary.

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 when-to-use or when-not-to-use guidance, and no alternative tool is named. The persistence sentence implies the intended context (recording discoveries across sessions), but any routing decision against sibling tools like capture, decide, or knowledge_rebuild is left entirely to inference.

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

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

Beyond the destructiveHint annotation, the description discloses the exact mutation ('Appends a [[wikilink]] to the source note') and, by calling it a *forward* link, implies the target note is not modified. That is meaningful effect-level context, though permissions/rate context is absent.

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 front-loaded sentences with zero filler: the action first, then the mechanism and its consequence. Nothing wastes space.

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

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

With a fully documented 4-parameter schema, a destructive annotation, and no output schema, the definition covers what an agent needs to call it. Only minor gaps remain, such as duplicate-link behavior or failure modes when the target note doesn't exist.

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 source, target, project, and workspace_path are already documented. The description adds no format or syntax detail (e.g., path vs note-name handling) beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a forward link between two vault notes') and names the downstream sibling it enables ('graph_related to discover the connection'). An agent can distinguish this linking operation from generic write/edit siblings 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 phrase 'forward link' implies directionality and the graph_related mention hints at the goal, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferred rather than 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?

The readOnlyHint annotation already establishes this is a safe read operation, lowering the bar. The description adds the auto-detection trait, but says nothing about how detail_level or max_tokens affect the result or what the returned document 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 short sentences, front-loaded with the core purpose and followed by the auto-detect caveat. Both sentences earn their place, though the overall brevity leaves real gaps unaddressed.

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 tool with a fully documented schema and no output schema, the description is minimally adequate. It omits what the 'context document' contains and how it relates to the 'generate_context' sibling, which an agent would need to choose correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, establishing a baseline of 3. The description only echoes the auto-detect behavior for 'project' and adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Get the context document for a project'), which is clear. However, it does not distinguish itself from the sibling 'generate_context', leaving ambiguity about whether this retrieves an existing document versus producing one.

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 only guidance is the CWD auto-detection behavior, which is really a parameter default rather than usage context. It never says when to reach for this tool instead of 'generate_context' or other context-related 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?

The destructiveHint=true annotation already flags the write/mutation risk, and the description adds useful context by disclosing that deletion is policy-driven and that a dry-run preview exists as a safeguard. It stops short of explaining irreversibility or what happens to archived vs deleted content.

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 the core action front-loaded and the safety tip second. No filler, nothing 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?

Given six optional parameters with full schema coverage, no output schema, and a destructive annotation, the description covers the essential risk and preview path. It could add a bit more on scope (project vs all) behavior, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so all six parameters, including defaults and the mode enum, are already documented. The description only restates the dry-run mode value, adding no new semantics beyond the schema 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?

States a specific verb pair (archive/delete) plus the resource (stale vault content) and the selection basis (retention policies). An agent knows what it does, though it doesn't differentiate itself from sibling maintenance tools like hygiene_report or worktree_gc.

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 one concrete workflow instruction: run mode='dry-run' first to preview. It does not state when pruning is appropriate versus alternatives, nor any prerequisites (e.g. permissions or project mapping) that would help an agent decide to invoke 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=true, so safety is covered. The description adds the vault-scoping constraint, but says nothing about truncation behavior, missing-path errors, or what the directory listing mode returns — the max_bytes cap in the schema hints at truncation that the description never addresses.

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; the verb and resource lead, and nothing is repeated from the title or schema.

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?

Safety is covered by annotations and params by the schema, but with no output schema the description should clarify what read actually returns in each mode and how truncation manifests. For a dual-mode tool with a 10MB byte cap, that omission leaves a real gap.

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

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

Schema description coverage is 100%, so all four parameters (including the non-obvious workspace_path constraint) are already documented in the schema. The description adds no parameter-level meaning beyond it, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource (read a file or directory listing) and names the domain (AI knowledge vault), which separates it cleanly from the write and search siblings. It does not explicitly call out those siblings, but the read/write contrast is self-evident.

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 mention of 'file or directory listing' implicitly tells the agent the tool has two modes selected by the path, but there is no explicit when-to-use guidance or routing against alternatives like search, extract, or graph_traverse. Usage must be inferred.

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 only declare readOnlyHint=false, so the description carries the real disclosure burden and does well: it names the exact artifact written (project-map.json locator) and the scoping behavior (knowledge jailed under projects/<slug>/). It does not mention permissions or reversibility, but adds meaningful context beyond the annotation.

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, front-loaded with the action and scope, followed by parenthetical side-effect details. Dense but no wasted sentences.

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 two-optional-parameter write tool with no output schema, the description covers purpose, side effect, and scoping. Nothing essential to correct invocation is missing, though permission/auth requirements are unstated.

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 both parameters are already well documented in the schema with defaults and key derivation. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 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?

States a specific verb ('Map') and resource ('repo to a vault project') and names the concrete effect (auto-detect the slug). The scope is clear enough to distinguish it from most siblings, though it never names an alternative tool directly.

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 explains why you would use it ('so vault-backed commands auto-detect the slug'), which implies the use case, but gives no explicit when-to-use vs when-not guidance or named alternatives among siblings like init or link.

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?

readOnlyHint=true already declares this is a safe read, so the safety burden is lifted. The description adds the content scope of the result but says nothing about behavior beyond that — no auth needs, data source, cost, or pagination/limit behavior beyond what the schema states.

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 tightly packed sentences with zero filler; the purpose and the trigger condition are both front-loaded and every clause earns its place.

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

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

With no output schema, the description usefully enumerates what the tool returns (sessions, interrupted work, tasks, next steps), which is exactly the burden it must carry. The main gap is the absence of routing guidance relative to the sibling 'session' tool.

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

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

Schema description coverage is 100%, so all four parameters (limit, format, project, workspace_path) are already documented in the schema. The description adds no additional parameter meaning, 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?

States a specific verb+resource ('Get resume context') and enumerates exactly what that context contains — recent sessions, interrupted work, in-progress tasks, suggested next steps. It distinguishes itself from generic tools, though it never explicitly contrasts with the similarly-named sibling 'session'.

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?

Explicitly says when to call it: 'Call this at session start to understand what happened before.' That is a clear usage context, but there is no when-not guidance and no named alternative (e.g. 'session' or 'project_context') to route between.

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?

Only destructiveHint=true is provided as annotation, and the description does not reconcile that with its safety-oriented framing — it never says what gets mutated, deleted, or overwritten, nor whether checkpoints persist. There is no auth, retention, or output behavior disclosed, so the full behavioral burden is unmet.

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 resource being managed, and no filler. It is efficient, though the middle sentence overlaps somewhat with the schema's field descriptions.

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 7-parameter mutation tool with no output schema, the description covers what is stored but omits what 'list' returns, ordering, and the destructive behavior flagged by annotations. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is 100% with descriptive per-parameter text (including which fields are required for 'add'), so the schema already carries the parameter semantics. The description adds no format, ordering, or cross-parameter detail beyond it.

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 the resource (rollback checkpoints) and the operations (store commit hashes with purpose/scope, mark follow-up work). It usefully clarifies that the tool manages checkpoints rather than performing an actual rollback, which is not obvious from the name. It does not, however, differentiate itself from any of the many sibling tools by name.

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 a rationale ('so rollback is safer') and implies the three flows through the action enum's semantics, but never states when to use this versus alternatives or any prerequisites/exclusions. Usage is only inferable.

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, so safety is covered. The description adds real behavioral context by revealing the matching engine (FTS5 porter stemming, which implies stemming-based recall) and that structured mode also matches frontmatter, but says nothing about result ordering, pagination, or how limits truncate.

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 compact sentences, front-loaded with the core operation and scope, with no filler. It is appropriately sized, though the second sentence is terse enough to feel borderline cryptic.

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 6-parameter read tool with no output schema, the description omits anything about result shape, ordering, or how limit interacts with paging. Scope and matching semantics are covered and safety is handled by annotations, so it is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely clarifies what the schema only labels: it explains that structured mode still matches frontmatter, which the enum description ('Search mode (default text)') does not convey. This is meaningful added meaning 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?

States a specific verb and resource (full-text search) plus its scope (this project) and the underlying implementation (SQLite FTS5 porter stemming). It is clearly distinguishable from graph/extract siblings, though it does not name any sibling explicitly.

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

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

There is no guidance on when to use this tool versus alternatives such as graph_related, read, or extract, and no statement of when to prefer text vs structured mode. The mention of structured mode implies a use case but never states the condition that selects 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 idempotentHint=true and destructiveHint=true, so the safety profile is largely covered. The description adds one useful side-effect detail ('On complete, persists a session note to the vault') but omits the concurrency/workspace-claim behavior implied by the allow_shared and workspace_path parameters, which is the key coordination trait.

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, front-loaded with the verbs and scope, followed by the one side-effect worth calling out. Zero waste and 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?

For a 15-parameter, multi-action tool with no output schema, the description is thin: it never maps params to the register/heartbeat/complete/list_active actions (and its verb 'update'/'query' do not even match the enum names). It is minimally viable given the strong schema coverage but leaves the action-parameter contract to inference.

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

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

Schema description coverage is 100% across all 15 parameters, so the schema carries semantics. The description adds only generic context ('On complete, persists...') and does not map the four action enum values to their relevant parameters, so baseline 3 is correct.

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 specific verbs (register, update, query) and the resource (active agent sessions) plus the domain (multi-agent coordination), so the tool's purpose is clear. However, it does not differentiate itself from the sibling tool 'register', which invites confusion about which to call.

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?

'For multi-agent coordination' implies the context of use and the sentence about persisting on 'complete' hints at workflow placement. But there is no explicit when-to-use versus the sibling 'register' tool, no prerequisites, and no when-not 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?

The annotations only declare destructiveHint=true; the description adds real behavioral context beyond that: resolution goes through skills.sh and its gen/socket/snyk audits, failing audits are blocked, and the unaudited GitHub path is a fallback gated on reachability. It still omits what gets overwritten on install and whether auth is required, so not a 5.

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 tightly packed sentences that front-load the action and source format before the audit policy. The audit sentence is dense but each clause carries distinct information, so only minor trimming is possible.

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 three params, full schema coverage, no output schema, and a destructive annotation, the description covers the audit/safety gate that the annotation does not. It is nearly complete, missing only install-target/overwrite and permission details.

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 source, select_skills, and allow_unaudited. The description only restates the source format (owner/repo or full URL) and adds nothing about selection semantics or the unaudited flag 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?

Specific verb (Install) plus resource (skills) plus source format (owner/repo or full URL). It is clearly distinct from the sibling skill_remove and skill_list_installed without opening any 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?

States conditional behavior (fail-audit skills blocked, unaudited fallback only when skills.sh is unreachable) but never says when an agent should prefer this over skill_validate or superskill, nor lists prerequisites. Usage context is implied rather than 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?

The readOnlyHint annotation already establishes the tool is read-only. The description adds that it lists skills installed locally from GitHub repos, providing scoping but no additional behavioral details such as return format or network behavior. This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that states the action and resource without wasted words. It is perfectly concise for the tool's simplicity.

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

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

For a simple list tool with no parameters, no output schema, and a read-only annotation, the description provides enough context to understand its purpose. There is no missing critical information.

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 are no parameters, and schema coverage is 100% by default. The description doesn't need to explain parameters. This baseline of 4 is appropriate for a zero-parameter tool.

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 (list) and resource (skills installed locally from GitHub repos). It distinguishes from sibling tools like skill_install and skill_remove, which perform different operations.

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 context is clear: use this tool when you want to see which skills are installed locally from GitHub repos. There are no explicit exclusions or alternatives mentioned, but given the simplicity of the list operation, the context is sufficient.

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

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

The destructiveHint annotation already flags the destructive nature. The description adds no further behavioral details, such as permanence, dependency effects, or potential side effects. It simply restates the action without enriching the agent's understanding of what happens when the tool is invoked.

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, clear sentence with no redundancy. It is front-loaded and immediately conveys the intended action.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is adequate to explain the action. The destructiveHint annotation covers safety context. It lacks only minor details about edge cases or prerequisites, but for a straightforward removal operation, this is sufficient.

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

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

Schema description coverage is 100%, and the parameter 'name' is described as 'Skill name to remove'. The tool description reiterates 'by name' without adding new meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description "Remove an installed skill by name" uses a specific verb (remove) and a clear resource (installed skill). It directly distinguishes from sibling tools like skill_install (adds a skill) and skill_list_installed (lists skills).

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

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

The description implies when to use the tool: when you want to remove a skill. However, it does not mention any alternatives (e.g., deprecate) or situations to avoid using it. No explicit exclusions or usage context beyond the obvious action.

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?

readOnlyHint=true already tells the agent this is a safe read, so 'without modifying it' largely restates the annotation. The description adds the concept of two validation profiles, which is useful, but says nothing about outcome behavior (errors vs. diagnostics) or scope limits.

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 that carries the verb, resource, criteria, and non-mutating guarantee with 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 no output schema, an agent cannot learn what a validation run returns (pass/fail structure, diagnostics). For a validation tool this is a meaningful gap, though the readOnlyHint and fully described params cover the invocation side.

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 rules, the profile enum, and workspace_path semantics are already fully documented in the schema. The description only alludes to the two profiles and adds no syntax or default detail (e.g. the anthropic 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?

States a specific verb (validate) and resource (native skill file) with the criteria it checks against (Anthropic or portable requirements). The verb 'validate' cleanly separates it from install/remove/list siblings without ambiguity.

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 'without modifying it' implicitly signals this is the non-mutating counterpart to skill_install, but no sibling is named and no when-to-use trigger is given (e.g. before install, after editing). Usage must be inferred.

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 declare destructiveHint=true, yet the description frames the operation purely as an additive write ('snapshot into the vault') and never says what the destruction is — presumably overwriting a prior snapshot or existing vault entry. With no auth, idempotency, or overwrite-semantics disclosure, an agent cannot judge the risk of re-running this on the same repo.

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 compact sentences, front-loaded with the concrete action and followed by the payoff. No boilerplate or restated field definitions; every clause earns its place.

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

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

No output schema exists and all parameters are documented, so the schema side is covered. However, for a tool flagged destructive with zero required parameters, the description should clarify what the snapshot replaces or overwrites; that gap keeps it at minimum-viable completeness.

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

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

Schema description coverage is 100%, so all five parameters are already documented, establishing a baseline of 3. The description echoes branch/dirty_files/last_commit but adds nothing about the auto-detection behavior of project or the workspace_path mapping constraint that the schema already covers.

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 and resource — 'Snapshot current git state (branch, dirty files, last commit) into the vault' — and enumerates the captured fields, so the agent knows exactly what the tool produces. It does not differentiate itself from any named sibling, which keeps it short of a 5.

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

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

'Helps avoid repeating repo discovery across sessions' implies the usage context (session-start discovery caching) but never states when to prefer it or what the alternative is. There are no exclusions or prerequisites, leaving the agent to infer the trigger 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?

Description adds meaningful behavioral context beyond the destructiveHint annotation: approve requires zero gaps, freeze pins a content hash and makes the spec immutable. These are consequential state changes an agent needs to know. It doesn't explain which specific actions are destructive (annotations only say destructiveHint=true globally) or what status 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?

Three compact sentences: purpose, action enumeration, and two critical behavioral rules. Front-loaded and every sentence earns its place.

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

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

For a 14-parameter tool with 100% schema coverage, the description targets the highest-value gaps: the action lifecycle and the invariants of approve/freeze. Missing is any guidance on the workspace_path fallback behavior or how 'gaps' are detected, but the core 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?

Schema coverage is 100%, so parameters are fully documented in the schema. The description mentions the fixed skeleton (goal, non-goals, constraints, context, files, acceptance, risks, rollback), which loosely maps to some fields but doesn't add syntax or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Manage deterministic plan specs') and explicitly enumerates the five actions (create, status, approve, freeze, list), which maps directly to the action enum. No sibling tool in the list covers plan-spec lifecycle, so it's distinguishable.

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

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

Provides action-specific rules ('Approve requires zero gaps', 'freeze pins a content hash and makes the spec immutable'), which implies the conditions for those actions. However, it doesn't say when to use spec vs. siblings like tickets, gate, or task, nor does it explain create-vs-list decision 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=true, so the safety profile is covered externally. The description adds useful behavioral context by naming the categories of content statistics returned (file counts, task breakdown, growth monitoring), but it does not describe return format, project-scoping behavior, or any server-side constraints beyond what the annotations and schema provide.

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 and immediately states the tool's function and its main outputs. It could be slightly more informative without becoming bloated, but the structure is efficient.

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 read-only tool with full schema description coverage and no output schema, the description gives an adequate high-level view of what is returned. It does not clarify how this view differs from related reporting siblings, but the core information needed to call the tool is not 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?

Schema description coverage is 100%, so both parameters (project and workspace_path) are fully documented in the schema itself. The description mentions that statistics are "for a project," which loosely connects to the project parameter but adds no syntax or format detail beyond the schema.

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

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

The description states a clear verb ("Show") and resource ("content statistics for a project") and enumerates what those statistics include: file counts, task breakdown, growth monitoring. It does not, however, distinguish this tool from related siblings such as status, telemetry, or project_context, leaving the agent to infer when this specific view is appropriate.

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, or which sibling alternatives exist. The only usage context comes from the input schema (e.g., project auto-detection and workspace_path omission rules), not from the description itself.

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, and the description aligns with this by using 'Show'. It adds context about what aspects of the state are visible (loaded skills, weights, recent sessions), which is valuable beyond the annotation. No contradictions.

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

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

The description is a single concise sentence with no filler. It front-loads the main purpose and immediately lists the key components, earning the maximum score for efficiency.

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 zero-parameter read-only status tool, the description is sufficiently complete. It names the core content areas (loaded skills, weights, recent sessions). While it doesn't specify output format or provide deeper details, the simplicity of the tool makes this acceptable. Sibling tools like 'stats' exist, but the description distinguishes the knowledge graph focus.

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 are 0 parameters, so the baseline is 4. The description doesn't need to explain parameters but effectively communicates the scope of the operation by listing what will be shown.

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 shows superskill knowledge graph state with specific components (loaded skills, weights, recent sessions). It uses a specific verb 'Show' and a resource, differentiating it from sibling tools like 'stats' or 'skill_list_installed' which likely focus on different aspects.

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 clearly implies when to use this tool: when an agent needs to inspect the current state of the superskill knowledge graph. It does not explicitly mention alternatives or exclusions, but the context is clear enough for basic 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 only declare readOnlyHint=false, and the description adds real behavioral context: phase governs methodology packs and budget rather than rule eligibility, and it explicitly excludes scraping skills.sh and executing plan flows/gates. However, it does not disclose the side effects implied by readOnlyHint=false (session activation learning, state mutation), leaving the write behavior unexplained.

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, front-loaded with the core purpose, with no filler sentences. It is dense and slightly jargon-heavy, but every sentence carries routing or scoping information and the size is appropriate for an 8-parameter tool.

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

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

Covers purpose, negative scope, and phase semantics for a moderately complex 8-parameter router, but with no output schema it never describes what a routed result looks like or what side effects (activation learning, budget enforcement) occur, leaving gaps for an agent invoking it blind.

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 one genuine semantic beyond the schema — that 'phase' selects methodology packs and budget, not individual rule eligibility — but says nothing additional about the other seven parameters, so the value-add is limited.

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 concrete verb ('Route a task') and resource ('curated in-repo packs and verified rules') with the selection inputs (language, keywords, symbols, file hints) named. It also carves out negative scope ('Does not scrape skills.sh or execute plan flows/gates'), which helps distinguish it from skill_install/gate, though it never names a sibling explicitly and the jargon ('packs', 'methodology') is dense.

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

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

Usage is implied rather than stated: the reader infers 'call this to load the right methodology for a task.' The description clarifies internal routing behavior (phase picks packs/budget) but gives no explicit when-to-use vs when-not-to-use guidance or named alternatives among the many skill_* 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?

The destructiveHint=true annotation carries the safety signal, and the description adds useful context that tasks are persisted as individual files under projects/<slug>/tasks/. However, it never discloses which actions actually mutate (update vs list/add/board), nor permissions or reversibility, so it partially duplicates structured data rather than enriching it.

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 purpose before the action list and storage note. No wasted words, though the storage detail is marginally secondary.

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 11-parameter, multi-action tool with no output schema and only a destructiveHint annotation, the description is adequate but thin. It omits action-to-parameter routing (left to the schema), return shape, and any behavioral caveats an agent would want before invoking update.

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

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

Schema description coverage is 100% and each parameter (including enum values and 'required for add/update' notes) is documented in the schema itself. The description adds no syntax, defaults, or formatting detail beyond that, which is the correct baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Manage project tasks') and enumerates the supported actions (add, list, update, board). It does not distinguish the tool from lookalike siblings such as 'tickets' or 'spec', so it stops short of a 5.

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

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

The description names the four actions but gives no guidance on when to use this tool versus alternatives like 'tickets', and no exclusions or prerequisites. Action selection is left entirely to inference from the enum.

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 only readOnlyHint=false available, the description carries the safety burden well: it discloses that telemetry is local and opt-in, that data never leaves the machine, that prompts are stored only as truncated hashes, and that destructive actions (enable/disable/clear) require explicit user authorization plus confirm=true. That is substantive behavioral context no annotation provides.

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: identity and action set first, then the authorization precondition, then the privacy guarantees. Every clause earns its place and nothing is repeated.

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-required-param settings tool with no output schema, the definition covers what the tool does, which actions mutate state, what authorization is needed, and the privacy model. Nothing an agent needs in order to invoke it correctly 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?

Schema coverage is 100%, so action, top, and confirm are already fully documented, including the confirm/authorization rule which the description merely echoes. The description adds no syntax, defaults, or edge cases beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource (local, opt-in rule-selection telemetry) and enumerates the five sub-actions it performs, so an agent knows exactly what the tool manages. It does not, however, differentiate itself from nearby siblings like stats or status, so it falls short of a 5.

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

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

It states a precondition for mutations ('require explicit user authorization and confirm=true'), which is real usage guidance, and 'defaults to status' is implied by the action enum. But it never says when to reach for this tool versus siblings such as stats or status, nor any when-not 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?

The readOnlyHint annotation already declares this as a safe read operation, so the description rightly focuses on the returned content ('pre-filled templates'). However, it does not disclose behavioral aspects such as whether the templates are static or dynamic, whether variables are required for certain types, or how listing vs. getting changes the output. With annotations covering safety, this is adequate but not rich.

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 and followed by a usage note. It is appropriately sized with no obvious filler, though the list of types is somewhat long and could be moved to the schema if it were part of an enum (it is not here, so it 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 read-only tool that returns templates, the description covers what is retrieved and hints at usage. However, it lacks details on return structure (although no output schema exists, the description could describe the shape of a template or the effect of variables), and does not clarify the default action or listing behavior. Completeness is minimal viable given the absence of an output 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 input schema already documents all parameters (type, action, variables). The description adds little param-level detail beyond the type enumeration; it does not explain the 'action' parameter or how 'variables' works. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb+resource: 'Get pre-filled templates' with a scope of 'common vault item types'. It goes further by enumerating all supported types (adr, prd, decision, etc.) and a use case ('Use to scaffold new documents'), which makes the purpose unambiguous. Even without distinct sibling names, it clearly distinguishes this tool from other vault operations like read/write/search.

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 a high-level usage context ('Use to scaffold new documents') but does not specify when to choose this tool over alternatives such as 'spec' or 'read'. It also omits any mention of actions (list vs get) and when to use each. The guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, so the safety bar is partly met structurally. The description adds useful domain behavior (data model fields, evidence slot, deterministic topological ordering for ready) but never explains what makes this destructive or what mutation/authorization semantics apply, which is the key gap for a destructiveHint 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?

Three sentences, front-loaded with purpose then action list then data model then one action's return guarantee; there is very little waste. The middle sentence is somewhat list-like, but overall it is tight and readable.

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 five-action tool with no output schema, the description should clarify what several actions return or do. It covers the data model and the behavior of ready, but leaves board (grouping?), list, and update opaque, and does not describe return shapes an agent would need to chain calls.

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 eight parameters, including per-field descriptions and enums. The description adds marginal value by naming the ticket data model (acceptance, blocked_by, requires_review, evidence), but adds no syntax or format detail beyond the schema.

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

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

States a clear verb ("Manage") and resource ("tickets derived from a frozen spec"), and enumerates the five actions, which lets an agent understand the tool's scope. However, it never differentiates itself from likely-related siblings such as task, spec, or evidence, so an agent must infer the boundary on its own.

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 action list implies which operation to pick, and "ready returns unblocked tickets in deterministic topological order" gives real context for one action. But create/list/board/update are named without any statement of when to use them, prerequisites, or exclusions versus alternatives, leaving usage largely implied.

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?

Beyond the single destructiveHint=true annotation, the description adds substantial behavioral context: fix is dry-run by default, file reclamation is quarantined and reversible, digests are persisted to the vault, and prompt inclusion requires authorization. This meaningfully lowers risk perception for the fix path. It does not, however, state permission/auth requirements or any rate limits.

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-loads the tool's domain in a short phrase, then devotes one sentence per action with no visible filler. Slightly dense with parentheticals, but every sentence carries actionable information.

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

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

For a 17-parameter, no-output-schema tool, the description covers the primary actions and key behavioral guarantees (dry-run, reversibility, persistence). Some specifics (what status returns, how findings are paginated or windowed) are left to the schema, but the agent has enough to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters, setting the baseline at 3. The description reinforces the action parameter's semantics (dry-run default, reversible reclamation) and mention of vault persistence, but adds little syntax or value beyond what the schema already contains.

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

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

The description states a specific verb+resource ('Session review + environment optimization') and then enumerates the three distinct actions (dig, fix, status) with what each produces. It is clear what the tool does, though it never names or contrasts a sibling (e.g., hygiene_report, doctor) to help distinguish this from other diagnostic 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 three action modes imply usage (dig to analyze, fix to repair, status to list past work), but there is no explicit when-to-use-this-vs-alternative guidance despite a crowded sibling set containing hygiene_report, doctor, and stats. Usage must be inferred from the action semantics.

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 declare idempotentHint=true and destructiveHint=false, and the description reinforces the safety profile with 'Nothing is ever deleted' plus enumerates exactly what gets installed. The confirm-gating behavior adds useful context beyond annotations. It does not describe reversibility or how to undo, leaving a small 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?

Three short sentences, front-loaded with the action and its artifacts, then the critical workflow constraint, then the safety reassurance. Every sentence earns its place with no 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?

For an 8-parameter install tool with full schema coverage and no output schema, the description covers what is installed, the required confirm workflow, and safety. It could say more about default behaviors for hooks/hosts/seed and what preview output looks like, but nothing essential 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?

Schema coverage is 100%, so all 8 parameters are already documented in the schema. The description only elaborates on confirm (preview vs apply), which the schema also covers; it does not add syntax or meaning for hooks, hosts, seed, or workspace_path. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Uses a specific verb (Install) on a named resource (shared build-cache policy) and lists the concrete artifacts it touches: policy file in .git/superskill, guarded post-checkout hook, and host session hooks. This clearly separates it from siblings like worktree_status or worktree_audit, though it does not explicitly name the alternative install/uninstall siblings (worktree_apply, worktree_uninstall).

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?

Gives explicit workflow guidance: call with confirm=false first to preview, and only pass confirm=true after the user agrees. This defines the intended two-step invocation clearly. It lacks explicit when-not guidance or named alternatives, so it falls short of 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 destructiveHint=true already declared, the description adds real value: it names the consent precondition, states the default is a non-mutating plan, and bounds the blast radius ('Never removes worktrees or user files'). It stops short of describing exactly what files/config it writes when confirmed, but the safety envelope is well disclosed.

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 purpose and immediately followed by the consent/confirm gate and the scope guarantee. 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?

For a 5-param, 0-required mutation tool with no output schema, it covers the essential agent questions: consent, default behavior, and scope of destruction. It omits partial-failure behavior and how item vs all_safe selection interacts, but nothing critical is missing.

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

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

Schema coverage is 100%, so item, confirm, json, all_safe and workspace_path are all documented in the schema itself. The description reinforces confirm's plan-vs-mutate semantics but adds no new syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Apply) and resource (selected audit recommendation items) and enumerates the item kinds it handles (policy/hook/seed/tool-prune). This clearly distinguishes it from the audit-producing sibling worktree_audit and from read-only siblings like worktree_status.

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 when the mutation actually happens ('Requires confirm=true to mutate; without it returns the plan'), which tells the agent to call it in dry-run first. It does not point at an explicit alternative tool for inspecting recommendations, so it stops short of 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?

readOnlyHint=true already establishes the safety profile, so 'Never deletes anything' largely restates the annotation. The description does add real context beyond the annotation by disclosing what the audit produces (safety verdicts, recommendation items) and that duplication detection covers build caches, but says nothing about performance cost or scope limits.

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, zero filler, and the most important fact (read-only, scoped audit) is front-loaded. Nothing repeats the tool name or wastes tokens.

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 convey the return shape, and it does at a high level (safety verdicts, recommendation items). All parameters are optional so there is little invocation risk, but the description could say more about what a verdict item looks like or how many worktrees are covered.

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 (json, sizes, worktree, workspace_path) including the default-all behavior and the slower sizes option. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource: a read-only audit of git worktrees plus build-cache duplication, scoped to 'this repo'. This clearly separates it from siblings like worktree_status and worktree_gc, though it never names those alternatives explicitly.

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

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

Usage is implied ('audit ... reports safety verdicts and recommendation items') but there is no explicit when-to-use versus when-to-use-something-else guidance, no mention of running it before worktree_gc or how it relates to hygiene_report. The agent must infer the pre-cleanup context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description reinforces it by framing the tool as a resolver rather than a mutator. It adds little beyond that, omitting the probing behavior, the timeout budget implications, and that no state is changed. Adequate but not rich given the lower bar set by annotations.

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 the action-and-scope front-loaded and the usage cue second; nothing is padded. The trailing parenthetical is slightly terse but still earns its place by naming the payload.

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 carries some return-value burden and does indicate the payload (cache dirs + hit-enabling flags), while the schema covers the json/shell output-format switch. For a read-only resolver it is nearly complete, missing only a note on what happens when no providers are detected.

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

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

Schema description coverage is 100%, so all five parameters (json, shell, providers, timeout_ms, workspace_path) are already documented in the schema. The description adds no parameter-level detail, 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?

Specific verb ('Resolve') plus a precise resource ('shared-cache environment variables for the current git worktree'), with a parenthetical clarifying the output payload. It does not name or distinguish itself from a potentially overlapping sibling such as env_facts, so an agent must infer the boundary.

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 gives explicit timing guidance ('Use before running installs/builds in a worktree'), which is genuinely actionable context. It stops short of naming alternatives or stating when not to use it (e.g., outside a git worktree).

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 only mark this as destructive and non-idempotent; the description goes well beyond them by disclosing that the default is a non-mutating dry-run, that mutations require confirm=true, that deletions are quarantine-only and reversible via undo, and that purge permanently deletes entries older than 14d. This is exactly the safety and reversibility context an agent needs before invoking a destructive tool, and it is consistent with destructiveHint=true.

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 first three sentences are well front-loaded with purpose, default behavior, and the safety gate. The trailing 'Filters: ...' sentence is a 14-item comma list that largely duplicates parameters already documented at 100% coverage, so it does not fully earn 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 an 18-parameter tool with no output schema and destructive annotations, the description covers the critical unknowns: dry-run default, confirm gating, quarantine reversibility, and permanent purge semantics. The remaining parameter detail is fully carried by the schema, so the description is nearly complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters including their formats and the undo/confirm/purge interplay. The description re-lists the filter names as a run-on enumeration but adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Reclaim rebuildable build-cache entries,' and specifies the scope options (project-wise or --all). An agent immediately knows this is a cache-reclamation tool. It does not, however, differentiate itself from potentially overlapping siblings like prune or hygiene_report.

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 establishes the operational default ('Default is a dry-run report') and the gate for mutations ('require confirm=true'), which implies usage. But it never states when to choose this tool over adjacent ones such as prune, worktree_audit, or hygiene_report, leaving alternative selection to inference.

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

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

With readOnlyHint=true already declaring the safety profile, the description's contribution is the enumeration of what the status reports (policy/hook state, per-worktree safety, cache bytes), which tells the agent the scope of inspection. It does not describe the return shape, whether results are cached/live, or any cost, so it adds modest value over the annotation.

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

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

A single compact line with the key noun ('Worktree cache status') front-loaded followed by a scoped list of reported facets. It wastes no words, though the fragment style is slightly terse rather than fully structured.

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 status tool with no output schema and fully documented parameters, the description covers the reported dimensions adequately and the annotation covers safety. An agent can invoke it correctly; only the exact return format is left unspecified.

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 json, budget, and workspace_path, including the constraint that workspace_path must map to this project. The description confirms the budget check is conditional but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description names a clear verb+resource combination ('Worktree cache status') and enumerates the specific facets reported: policy/hook state, per-worktree safety, cache bytes, and an optional budget check. It is concrete enough to act on, though it never distinguishes itself from nearby siblings such as worktree_audit or worktree_env, so an agent must infer the boundary.

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 when-to-use guidance at all: nothing says when to call worktree_status rather than worktree_audit, worktree_env, or worktree_activate. The only usage-adjacent signal ('optional budget check') indicates a parameter behavior, not a scenario where 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?

With destructiveHint=true already set, the description adds genuinely useful context beyond the annotation: exactly which artifacts are removed, that caches survive by default, and that the purge path merely quarantines the repo's cache namespace and remains reversible. It is consistent with the destructive annotation and materially lowers the agent's risk of surprising data loss.

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

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

Two sentences, zero filler, with the default (non-destructive) behavior front-loaded and the conditional destructive branch parenthetically qualified. Every clause carries information an agent needs.

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 destructive mutation tool with no output schema, the description covers what is removed, the default safe behavior, the gating conditions, and reversibility. It stops short of stating whether hook/metadata removal is itself reversible or what state the tool expects to find, but the essentials for a correct call are present.

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

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

Schema description coverage is 100%, so the per-parameter baseline is 3. The description goes slightly beyond the individual schema blurbs by spelling out the conjunction (purge_local=true AND confirm=true) and reiterating reversibility/quarantine semantics, which clarifies how the two booleans interact rather than documenting them in isolation.

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 (Remove) plus the exact resource (worktree-cache integration) and enumerates what is removed: host session hooks, post-checkout hook, policy metadata. It is clearly distinguishable from worktree_activate/worktree_apply by its uninstall framing, though it never explicitly contrasts itself with nearby siblings like worktree_gc or worktree_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 gives a precise operational condition for the destructive path (caches are only purged when purge_local=true AND confirm=true), which tells the agent when the risky branch fires. It does not, however, say when to choose this tool over alternatives such as worktree_gc, nor does it state prerequisites (e.g., integration must already be installed), leaving tool selection implied.

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 flag destructiveHint=true, so the safety profile is partly covered. However, the description adds nothing beyond that: it never warns that overwrite mode destroys existing file content, nor mentions workspace/permission requirements for this mutation.

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. It is efficient, though its brevity shades into under-specification rather than crispness.

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 destructive write tool with five parameters, three write modes, and no output schema, one sentence is thin. The description does not cover what gets destroyed on overwrite, where the file lands, or what the caller gets 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 description coverage is 100%, so all five parameters including the mode enum and the workspace_path caveat are already fully documented in the schema. The description adds no format, syntax, or default detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: "Write or append to a file in the AI knowledge vault." The action and target are unambiguous, though it does not explicitly distinguish itself from siblings like read, capture, or template.

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 indication of when to use this tool versus read, capture, template, or other vault-mutating siblings, nor any stated preconditions. 'Write or append' hints that modes exist but gives no guidance on choosing between them.

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