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

The description discloses that it writes a file under .agentpack/evidence/ and adds a ledger event, which is useful context beyond the annotations' readOnlyHint=false. However, it does not mention overwrite behavior, whether directories are created, or failure modes. Annotations already cover core traits, so the description adds moderate value.

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 pack purpose, usage guidance, and parameter interplay without unnecessary detail. It is front-loaded with the primary function and returns an id. Slightly long but 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?

The description covers what the tool does, when to use it, how to provide evidence (inline or file), and what the id is used for. With no output schema, it doesn't over-explain return values. It could mention that the ledger event is also a record, but overall it is complete for 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%, but the description adds key semantics: 'content is ignored when path is set' and 'kind json stores the file with a .json extension' and that command/exitCode are stored as metadata. This goes beyond the schema descriptions and clarifies parameter relationships.

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 ('Store') and resource ('verification output as a file under .agentpack/evidence/ plus a ledger event'), and it explains the returned evidence id's purpose for reference from other tools. This clearly distinguishes attach_evidence from siblings like record_decision and task_update_verification.

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 explicitly says to call for meaningful verification worth preserving and provides aggregation guidance ('for small tasks prefer one aggregated evidence item over many per-command items'). It also explains the two input modes (inline content vs. path). It does not name alternative tools when not to use, but the guidance is clear enough.

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

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

The description reveals that the tool writes only a new bundle file and leaves pack state unchanged, which is critical side-effect information given all annotation hints are false. It also mentions the output is 'redacted,' adding behavioral nuance.

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. The first establishes purpose and scope; the second clarifies the side-effect boundary. No redundant wording.

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 4 params, full schema coverage, and no output schema, the description adequately covers purpose, output, and side effects. It's sufficient for an agent to select and invoke the tool.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The tool description itself doesn't add parameter details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool exports one Task Passport with decisions, dead ends, source conclusions, and optionally evidence to a redacted agentpack.task-bundle JSON file. It distinguishes from siblings like bundle_inspect (inspect) and bundle_import (import) by specifying the export action and sharing purpose.

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

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

The description provides clear context: 'for sharing tasks across repos, machines, or agents.' It doesn't explicitly name alternatives or exclusions, but the context is sufficient to infer when to use it.

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

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

The description goes far beyond the annotations by detailing that the default is a read-only plan, a write import runs under pack lock, creates a parked task, resets verification to unknown, retains bundle and manifest, and never changes the current-task pointer. This is rich behavioral context not captured in 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?

The description is four well-structured sentences, front-loaded with the purpose, followed by default behavior, write side effects, and a safety note. Every sentence earns its place with no redundancy.

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

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

Given the tool has no output schema, the description adequately explains the return (read-only plan) and fully discloses the side-effect profile of write mode. It also includes safety guidance, making it complete for agent decision-making.

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

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

The input schema already covers all four parameters with clear descriptions, including the write param. The description reinforces the write behavior but does not add new parameter-level meaning beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly states 'Import a task bundle into this pack' with a specific verb and resource, and distinguishes itself from siblings by explaining the default read-only plan mode and the write behavior, making it distinct from bundle_inspect and bundle_import_plan.

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

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

The description explicitly advises to 'Inspect or plan untrusted bundles first', pointing to alternatives for inspection/planning. It also clarifies when to use write=true for actual import, providing clear context on usage, though it does not name sibling tools directly.

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 mark readOnlyHint=true, and the description reinforces with 'without writing anything' and 'explicit read-only guarantee.' It adds behavioral detail about the return: 'create, idempotent, or conflict actions,' which is not in 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 sentences, zero wasted words. The first sentence states the core function and guarantee; the second gives a direct call-to-action tying to bundle_import.

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 it's a preview tool with no output schema, the description adequately describes return categories (create/idempotent/conflict) and the read-only nature. It also clarifies the relationship to bundle_import. Minor gaps like error handling are acceptable for this scope.

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 each parameter (json, path, asNew) is already well-documented. The description adds no additional parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description uses the verb 'Plan' and identifies the resource 'task bundle import against this pack' with the scope 'without writing anything.' It clearly differentiates from bundle_import by stating it previews what the write would do.

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?

'Call to preview exactly what bundle_import with write: true would do' provides explicit guidance on when to use this tool (as a pre-flight to bundle_import). It implies the alternative is bundle_import for actual execution, though it doesn't explicitly name 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?

The description reinforces the readOnlyHint annotation with the explicit statement 'Read-only — never writes pack state,' adding a concrete behavioral guarantee beyond the annotation. It also signals safety for untrusted files, which is valuable context. The openWorldHint is not contradicted.

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, each packing distinct value: the first describes what the tool does and its output categories, the second provides safety and usage timing. No redundant words; information is front-loaded and 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?

Even without an output schema, the description enumerates the key output categories (schema/digest status, origin, records, warnings) and gives safety guarantees and usage timing. For a read-only inspection tool with full annotations and schema, this is sufficient for an agent to select and invoke the tool 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%, with both parameters (path and json) already described clearly in the input schema. The description does not add additional parameter-level meaning—it only mentions 'task bundle file' without elaborating on the path or json flag. Baseline 3 is appropriate.

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

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

The description clearly states the tool validates and summarizes task bundle files, listing specific output aspects (schema and digest status, origin, included records, warnings). The verb 'validate and summarize' plus the resource 'task bundle file' precisely defines the action, and the mention of 'untrusted' and 'before planning or applying an import' distinguishes it from sibling tools like bundle_import_plan and bundle_import.

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

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

The description explicitly tells when to use the tool: 'Call before planning or applying an import of a bundle you did not produce.' This gives clear contextual guidance. However, it does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a full 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false; the description complements this by disclosing that it writes under .agentpack/checkpoints and overwrites the pack-level status/next actions that seed the next session. It does not explicitly warn about overwriting prior checkpoint state or state permissions, so it stops short of full 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?

Two front-loaded sentences: the first defines what is saved, the second defines when to call it. No filler, and the usage triggers are placed at the end where they are easy 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?

For a no-required-param, no-output-schema mutation tool, the description covers what is written, where, and when. It omits edge-case behavior such as what happens when all params are empty or how repeated calls interact (relevant given idempotentHint=false), which leaves a minor gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning by tying 'summary' to progress since the last checkpoint and 'nextActions' to seeding the next session's load_context. It also reveals implicitly captured data (git branch/commit/diff, task id) that are not parameters, which helps the agent understand the write.

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 (Save) plus resource (durable progress checkpoint) and its location (.agentpack/checkpoints), and enumerates what it captures (summary, git state, task id, pack-level status/next actions). This clearly separates it from siblings like load_context, resume, and task_update.

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 when-to-use triggers (after meaningful progress, before ending a session, before risky changes) and an explicit when-not (not after every small step). It also explains the downstream effect on load_context, so an agent can reason about sequencing.

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 mark it read-only, and the description reinforces this with 'Read-only.' It adds behavioral context beyond annotations by describing the default comparison (previous vs latest) and the exact data presented (summaries, status lines, git refs), which is valuable for callers.

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

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

Three concise, front-loaded sentences. Each sentence contributes either functionality, defaults, or usage guidance. No redundancy or filler.

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

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

For a simple read-only tool with full parameter schema coverage and no output schema, the description effectively conveys purpose, usage scenario, default behavior, and output content. It is sufficiently complete for an agent to select and 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 coverage is 100%, so parameters are fully documented in the schema. The description's mention of defaults aligns with the schema but does not add new semantic meaning beyond what schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare two checkpoints' with specific output details ('summaries, status lines, and git refs side by side'). This distinct verb+resource combination differentiates it from sibling tools like checkpoint or bundle_inspect.

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 clear usage context: 'Call to see what changed between sessions' and explains default behavior. However, it does not explicitly mention alternatives or when not to use, 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?

Annotations declare readOnlyHint=true, and the description adds 'Read-only' while also revealing token-budgeting behavior and the presence of gate warnings. This goes beyond the annotation by explaining what the resume includes and how the tool handles queries, though the exact output format is not specified.

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

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

The description is concise yet information-dense, using three sentences to convey the core function, usage frequency, and safety note. Each clause contributes value, and key facts are front-loaded in the first 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?

With read-only annotations and a fully described schema, the description explains what the resume contains (status, git, decisions, dead ends, conclusions) and when to call/re-call. Although there is no output schema, the content outline is sufficient for an agent to understand the tool's behavior and expected output.

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

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

Schema coverage is 100% with detailed param descriptions for query, budget, and preset. The description only references 'query or budget' in usage guidance without adding new semantic detail, so the baseline score of 3 applies as the schema carries 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 clearly states the tool loads a token-budgeted markdown resume of Agentpack state, enumerating specific content like Task Passport status, git state, decisions, and gate warnings. This distinguishes it from sibling tools by its start-of-session context-loading purpose and explicit resource scope.

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

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

The description provides explicit usage guidance: 'Call once at the start of a session or task, before reading code; re-call only for a different query or budget.' This establishes when to use the tool, when not to re-call, and the rationale for doing so, though no alternative tool names are mentioned.

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

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

Annotations are all false, so the description carries the burden. It discloses the write side effect ('Writes one event under .agentpack/') and redaction behavior ('secret-like values are redacted'), which goes beyond the minimal annotation information. However, it doesn't mention idempotency explicitly, though annotations already say idempotentHint=false.

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 primary action. Every word earns its place; no fluff or redundancy.

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

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

For a simple 3-parameter logging tool with no output schema, the description covers purpose, usage, side effect location, and security behavior. It's fully sufficient for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the general context of redaction but doesn't add specific parameter-level meaning 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?

The description clearly states the tool's verb and resource: 'Record an approach that failed.' It also distinguishes from siblings by noting it's for durable abandonments, not debugging iterations, which separates it from record_decision and other logging 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?

Explicit when-to-use: 'Call when an attempted direction is abandoned for a durable reason' and when-not-to-use: 'not for ordinary debugging iterations.' This provides clear context without needing to name alternatives.

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

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

Annotated readOnlyHint=false already indicates a write, but the description adds location ('writes one event under .agentpack/') and a security behavior ('secret-like values are redacted'), which are not present in structured annotations. This provides valuable behavioral context without contradicting any 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?

Three sentences with no filler: the first states the purpose and persistence, the second gives usage boundaries, and the third discloses location and redaction behavior. Every sentence earns its place and is front-loaded.

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

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

For a simple write tool with no output schema, the description covers purpose, when to use (and not use), the write location, and redaction behavior. This is complete enough for an agent to select and invoke the tool correctly, especially given the high schema coverage and distinction from siblings.

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

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

The schema describes all three parameters (text, files, evidence) with 100% coverage, so the baseline is 3. The description does not add parameter-specific detail (e.g., format of files or evidence), but the schema is sufficient; the redaction note is general rather than parameter-specific.

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

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

Description uses the specific verb 'Append' and names the resource 'technical or product decision to the Agentpack ledger', clearly stating the persistence goal so future sessions inherit it. This distinguishes it from sibling tools like record_dead_end or record_source.

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 states when to call: 'decisions that matter beyond this session (architecture, contracts, tradeoffs)' and when not to: 'not for routine preferences or per-edit narration'. This provides clear usage criteria and exclusions without needing to reference 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 description discloses the write behavior ('Writes under .agentpack/'), the caching mechanism (stores content hash with summary, reusable until file changes), and the durable conclusion nature. These details add meaningful context beyond the annotations, especially given 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 description is concise and front-loaded: a clear purpose statement, followed by usage guidance and a storage side note. Every sentence carries useful information without fluff or repetition.

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

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

Given the simple parameter set, absence of output schema, and provided annotations, the description is complete: it states what it does, when to use it, where it writes, and the cache invalidation behavior. There are no significant gaps in understanding how to invoke and use the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that 'summary' is always expected with a fallback to a generic 'Reviewed source.' It also clarifies how the summary is used with the content hash, providing value beyond the schema.

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

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

The description clearly states a specific verb ('Record') and resource ('source file in the Source Cache'), explaining the caching mechanism and reuse. It distinguishes itself from sibling tools like record_decision and record_dead_end by focusing on source files and content hashes.

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

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

Explicit guidance is given on when to use ('Call after inspecting an important file when the conclusion is reusable') and when not to ('do not record every file read'), plus when to re-record ('only when the conclusion itself changed'). This provides clear context for selecting this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces and expands this by asserting 'never pushes, tags, publishes, or creates GitHub Releases,' which adds specific side-effect guarantees beyond the generic annotation. It also clarifies the local scope of the report, providing useful behavioral context.

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

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

The description is two sentences, front-loaded with the core purpose ('Report local release readiness'), followed by content details, a read-only caveat, and usage context. Every sentence earns its place with no redundant or filler text.

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 enumerates the categories of information reported (release metadata, Trusted Publisher wiring, manual release-prep commands), covers the read-only safety profile, and specifies when to call it. For a parameterless report tool, this provides complete context for selection and invocation.

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

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

The tool has zero parameters, so schema coverage is inherently 100%. The description compensates by outlining the content of the report (metadata, Trusted Publisher wiring, commands), giving the agent meaningful expectations for what the tool returns despite having no parameters to document.

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

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

The description clearly identifies the action ('Report'), the subject ('local release readiness'), and specifies the exact content (release metadata, Trusted Publisher wiring, manual release-prep commands). It distinguishes this tool from routine work by noting it's for release preparation, making it distinct from siblings.

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

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

The description explicitly states 'Call when preparing a release, not during routine work,' providing both a clear when and when-not. However, it does not name any alternative sibling tools, so it stops short of the full 5 which requires explicit alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces with 'Read-only'. It adds useful behavioral detail beyond annotations: one line per event, timestamp/type, and chronological ordering. This helps the agent understand output expectations.

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 effectively cover purpose, usage, output format, and read-only nature. Every phrase earns its place with no redundancy or wasted words.

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

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

For a simple read-only list tool with one optional parameter, the description is fully sufficient. It covers event scope, output shape, usage timing, and exclusion from the routine loop, requiring no 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?

The single parameter 'limit' is fully described in the schema (default 30). The description adds no additional meaning 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 clearly states the tool prints a chronological timeline of ledger events, listing specific event types and output format. It also differentiates from siblings like resume by noting 'when a resume is not enough'.

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 states when to use ('audit how the task history unfolded') and when not ('not part of the routine load_context/checkpoint loop'). References resume as the alternative that falls short, providing clear usage context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context beyond annotations, including the resume contents and that it behaves identically to load_context but with adjustable query/budget. The read-only statement reinforces the annotation without contradicting 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?

The description is two sentences, front-loaded with the core action and contents, then gives usage guidance and a read-only note. Every sentence serves a purpose with no redundancy or filler.

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

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

The description covers purpose, contents, usage timing, and safety for a moderate-complexity tool. While no output schema exists, the description adequately implies the markdown resume output. It could have elaborated on exact return formatting or edge cases, but overall it is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description references 'query or budget' but does not add meaningful parameter detail beyond what the schema already provides for query, budget, and preset.

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

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

The description clearly identifies the tool as generating a token-budgeted markdown resume with specific contents (Task Passport state, git state, query-relevant records, gate warnings). It also explicitly distinguishes resume from load_context by positioning it as the ad-hoc re-read variant.

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 explicit guidance: prefer load_context at task start, use resume for mid-session re-reads with different query or budget. This directly addresses when to use the tool vs. alternatives and provides exclusion criteria.

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 adds 'Read-only,' reinforcing that. Beyond annotations, it discloses the mechanism ('by re-hashing the files') and the purpose of filters ('for stale source-cache triage'). This adds meaningful context about how the tool behaves without contradicting 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 sentences plus a one-word safety indicator. The main action is front-loaded, usage guidance follows, and every phrase earns its place. No fluff or redundancy.

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

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

For a simple read-only tool with three optional boolean parameters and no output schema, the description covers purpose, usage context, and parameter rationale. It is self-contained and gives the agent enough to decide when to call and what to expect, especially with annotations supporting the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by connecting 'changed/missing filters' to the tool's purpose ('for stale source-cache triage'), explaining why you'd use those flags. It does not repeat schema descriptions but adds operational context.

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

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

The description opens with a specific verb and resource: 'Check whether recorded source conclusions are unchanged, changed, or missing by re-hashing the files.' It clearly distinguishes itself from siblings like load_context and task_audit by focusing on stale-source checks via re-hashing. The purpose is unambiguous and not a tautology.

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

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

Explicit guidance is given: 'Call when you need a full stale-source check beyond what load_context already showed; do not repeat it when a recent load_context, task_audit, or status check answered the question.' This states both when to use and when not to use, naming alternative tools and providing a clear decision rule.

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 adds meaningful behavioral context: it is 'advisory-only', 'risk-proportional', does not block lifecycle actions, and stays read-only. It also explains the kind of evidence produced at different risk levels, which is useful and not contradicted 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?

Each sentence earns its place: purpose, exclusions, usage timing, skip condition, and read-only status. It is front-loaded with the core action and resource, and the parenthetical adds necessary detail without being bloated.

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 one optional parameter and no output schema, the description covers purpose, output type, usage timing, limitations, and safety profile. It explains what evidence is produced at different risk levels, so an agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, and the only parameter ('json') is already described in the schema as returning structured JSON instead of formatted text. The description adds no parameter-specific information, but none is needed because the schema already fully documents the parameter.

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

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

The description opens with a specific verb and resource: 'Audit the current Task Passport for continuity risks.' It further distinguishes itself from siblings by explicitly stating what it does not do ('does not judge semantic correctness or block lifecycle actions'), so an agent can separate it from tools like release_preflight or task_update_verification.

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 explicit when-to-use conditions: 'Call before finalizing, after a long gap, or when drift is suspected.' It also provides a clear skip condition: 'skip when a recent audit already answered it.' This is strong usage guidance even without naming sibling tools.

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

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

The description adds non-obvious behavioral context beyond annotations: it returns only non-blocking hygiene and adversarial-verification advisories, never judges semantic correctness, and does not block completion. This is valuable and complements the destructiveHint and readOnlyHint annotations without contradicting them.

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 pack the core action, preconditions, alternatives, force behavior, and return characteristics with no filler. Every sentence earns its place and critical information is front-loaded.

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

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

Given there is no output schema, the description sufficiently describes the return behavior (non-blocking advisories only). It covers preconditions, alternatives, force semantics, and limits of the tool. A minor gap is not explicitly stating irreversible/destructive finalization, though the annotation and 'Close' imply it.

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

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

The schema already covers all four parameters at 100%, but the description adds practical insight by linking status to the verification precondition and clarifying that force is required for accepted finalization with remaining next actions. This goes beyond what the schema alone states.

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

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

The description clearly identifies the action ('Close the current Task Passport') and the resource being acted upon. It also distinguishes itself from task_park by explicitly naming it as the alternative for deferred work, making the tool's purpose immediately recognizable.

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 explicit usage conditions: verification must already be passed, failed, or accepted, or status must be passed explicitly. It also directs the agent to task_park for deferred work and explains when force is required, eliminating ambiguity about when this tool should be used over 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 description adds meaningful behavioral context beyond the readOnlyHint annotation by listing what the generated handoff includes and explaining that its purpose is to let another party continue the work. It also confirms 'Read-only,' matching the annotation. It doesn't discuss side effects or failure modes, but for a zero-parameter read-only tool the disclosure is sufficient.

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 and front-loaded with the core action and output structure. The first sentence packs the purpose and content list; the second adds a crisp usage instruction. Every word earns its place, with no fluff or repetition.

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

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

Given the zero-parameter schema, the presence of readOnlyHint, and the absence of an output schema, the description is complete: it names the output sections and the exact timing for use. An agent can confidently select and invoke this tool without needing further clarification.

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?

This tool has zero parameters, so the schema fully covers the input side with 100% coverage. The description appropriately focuses on behavior and output content rather than parameter details, meeting the baseline for a no-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 opens with 'Generate a compact handoff for the current Task Passport' — a specific verb and resource — and enumerates the exact sections the handoff contains (objective, constraints, write scope, next actions, verification, drift, audit summary). This clearly differentiates it from sibling tools by focusing on context transfer to another agent, not just status reporting.

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 clear usage trigger: 'Call before switching contexts.' It also specifies the intended audience ('another chat, client, worktree, or agent'). However, it does not explicitly mention when not to use it or contrast with alternatives like checkpoint or task_park, so it's not a full when/when-not guide.

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 trailing 'Read-only' merely reinforces it. Beyond that, the description discloses useful behavior: filters combine with AND and the current task is marked with an asterisk, which the schema and annotations do not state. Return-value shape is not covered, but that is a minor gap.

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

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

Front-loaded with purpose, then defaults, then filter/formatting behavior in compact clauses separated by semicolons. No wasted sentences, though the telegraphic style packs several distinct ideas into a dense block.

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, no-required-param list tool with no output schema, the description covers the default scope, the full-history escape hatch, filter combination logic, and result-shortening flags. An agent has enough to call it correctly; only return-format expectations are left implicit.

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

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

Schema description coverage is 100%, so the parameters (all, status, scope, compact, limit) are already well documented in the schema, establishing the baseline of 3. The description echoes the key defaults (status vs all, compact/limit shortening) but adds no syntax or format detail beyond the structured fields.

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 ('Find Task Passport ids or inspect task history'), covering both lookup and history inspection. It is clearly a listing/inspection tool, distinguishable from mutation siblings like task_update or task_start. It does not explicitly name sibling alternatives, but the purpose itself is unambiguous.

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 concrete default behavior ('Without status lists open tasks') and how to widen scope ('pass all: true for full history'), which is real usage guidance. However, it never states when to prefer this tool over siblings such as task_status or task_audit, 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?

Annotations already indicate destructiveHint=true, but the description adds meaningful context: parking preserves verification state and is resumable, and it does not finalize. This goes beyond the annotation to clarify the exact behavioral semantics, though it doesn't mention any authorization needs or additional 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 three sentences, each earning its place: first states the action and benefit, second explains the intended use case, third provides a critical exclusion. No fluff or repetition.

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

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

For a zero-parameter tool with no output schema, the description fully covers its purpose, usage context, exclusions, and related tools (task_switch, task_finalize). 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?

With zero parameters and 100% schema coverage, there is no parameter information to add. The baseline for zero-parameter tools is 4, and no additional parameter semantics are needed.

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

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

The description clearly states the action ('Mark the current Task Passport parked') and its purpose ('so unrelated work can start without finalizing it'). It distinguishes this tool from siblings by explicitly contrasting with task_finalize and mentioning task_switch for resumption.

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

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

Provides explicit when-to-use guidance ('intentionally deferred work'), explains what it preserves, and gives a clear exclusion ('Do not park to skip verification of finished work') with the correct alternative tool named (task_finalize). This is exemplary usage 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?

All four annotation hints are false, so the description carries the burden of behavioral disclosure. It reveals persistence behavior ('persisting under .agentpack/'), a conditional refusal to overwrite active tasks, and the writeScope gate requirement. These are genuine behavioral traits beyond what the schema or annotations provide. Lacks mention of return values or side effects on failure, but is reasonably transparent.

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

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

Two sentences, front-loaded with the core action, followed by usage conditions and a critical parameter hint. No filler or repetition of schema details. 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?

With 7 parameters, no output schema, and uninformative annotations, the description covers the essential behavioral contract: creation, persistence, current-task semantics, refusal conditions, and gate interaction. It does not explain return values or error handling, but for a create tool with this richness, it is largely complete. Minor gap: no mention of what happens to an existing current task besides refusal, but that is implied.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by singling out writeScope: 'Declare writeScope so the task gate can protect the task's boundaries' – explaining why this parameter matters and how it interacts with the system. This extra context goes beyond the schema's basic description of the 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?

The description opens with 'Create a new Task Passport and make it current, persisting it under .agentpack/' – a specific verb (create), resource (Task Passport), and outcome (make current). This clearly differentiates it from sibling tools like task_park or task_finalize, which manage existing tasks rather than creating them.

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

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

Explicitly states when to call: 'Call when starting a coherent phase of work and no task is active'. It also provides exclusions and alternatives: 'it refuses to replace an active, blocked, or verifying current task — park or finalize that task first'. This gives clear when/when-not guidance and names alternative tools.

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 and openWorldHint=false, so the 'Read-only' clause is partly redundant. The description still adds real behavioral context: gate warnings always pertain to the actual current task even when inspecting another id, and no source-cache scan occurs. It does not disclose pagination or output volume, which is a minor gap.

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

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

Default behavior is front-loaded in the first clause, then the two deviations from default. The single dense sentence is efficient, though the 'Gate warnings' aside is slightly intrusive to the flow.

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 reasonably: a compact state line by default, and objective, constraints, next actions, and verification in the id/full view. It is complete enough to call correctly, though it never mentions lifecycle side effects beyond asserting none.

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

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

Schema description coverage is 100%, so both parameters are already documented, making 3 the baseline. The description restates the roles of id and full without adding format, syntax, or edge-case detail beyond the schema's own wording.

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

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

The description states a concrete verb and resource ('Print a compact current-task state line') and enumerates the three operating modes (default, full: true, id). It explicitly distinguishes itself from the sibling task_audit, so an agent can separate the two without opening 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?

It names the default behavior and the conditions that select each alternative ('pass full: true for the detailed current view, or id to inspect a selected Passport'), and it routes the full continuity audit to task_audit explicitly. Nothing about mode selection 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?

Goes well beyond the annotations (which only state destructive/non-idempotent/non-readonly). It discloses the transactional boundary ('same locked transaction, after validating the target') and the full verification state machine: a parked target with pending/unknown verification resumes as active, one with a final verdict resumes as verifying and stays frozen until verification returns to pending.

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 core action, then the parkCurrent behavior, then edge cases. Dense but every sentence carries behavioral information; the verification-state sentence is heavy but necessary for correct invocation.

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

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

For a destructive, non-idempotent mutation with 2 params and no output schema, it covers prerequisites, atomicity, and target-state rules. It omits error/conflict handling beyond 'closed targets cannot be switched to' and any indication of what the call returns, which slightly limits 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying which current states parkCurrent can handle (active/blocked/verifying) and that parking preserves verification and bound HEAD, which the schema description does not state.

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: it switches the current 'open Task Passport' to another by id. This clearly differentiates it from siblings like task_park and task_finalize, which it explicitly references. The 'Task Passport' terminology is domain jargon, but the action is unambiguous.

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 real routing guidance: use parkCurrent:true to switch in one atomic call, otherwise park or finalize the current task first, and closed targets cannot be switched to. It does not name sibling alternatives by name (task_park/task_finalize are only implied), but the when/when-not conditions are 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 flag destructiveHint=true and idempotentHint=false, and the description earns extra credit by disclosing append-plus-deduplicate semantics, that omitted fields are preserved, that empty/no-op updates fail, and that replaced constraints persist in task history. It does not mention permissions or rate limits, but for a patch tool the behavioral picture is strong.

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 core operation and mutation model in the first sentence, then explains the two flags in order. Dense but nearly every clause carries a distinct rule; slightly long for the payoff.

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-param, no-required-param patch tool with no output schema, the description covers the mutation contract (append/replace/preserve/fail) thoroughly. It omits error/response behavior, but with no output schema and destructive hints already declared, that gap is minor.

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; the description adds value by generalizing the append-vs-replace semantics across the list fields and clarifying that the booleans act on the accompanying list parameter (or clear it). The risk and objective scalar parameters are left to the schema, which is adequate given full 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 and resource ('Patch the current Task Passport') and immediately scopes it with 'without changing lifecycle status', which cleanly separates it from task_status, task_finalize, and task_switch. An agent can distinguish it from siblings without opening a 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?

Gives concrete conditions for the two switch flags ('to clear a stale plan before finalizing', 'constraints that are obsolete or superseded'), which is real usage guidance. It stops short of naming when NOT to use the tool or pointing at a specific alternative tool for full rewrites.

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

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

The description states 'identical repeated calls are no-ops,' which directly contradicts the idempotentHint=false annotation. It also fails to address the destructiveHint=true annotation, leaving potentially destructive behavior undisclosed.

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, each earning its place: purpose, lifecycle effects, and sequencing/idempotency. No filler or redundancy, and the most important information is front-loaded.

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

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

Covers core purpose, state transitions, and call sequence, but given the no-output-schema and destructiveHint=true annotations, it omits return value, potential destructive side effects, and error/failure handling. This is a significant gap for a mutation 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 already covers all parameters, but description adds meaningful context: it distinguishes 'passed, failed, or accepted' as final verdicts versus 'pending or unknown' that reset to active, and links evidence to attach_evidence. This enhances understanding beyond the terse schema descriptions.

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

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

Description uses a specific verb ('Update') and resource ('current Task Passport verification state'), clearly distinguishing it from general task tools like task_update. It also defines the scope with lifecycle effects, making the tool's purpose unambiguous.

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

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

Provides explicit usage context by instructing to call after attach_evidence and explaining lifecycle transitions for final vs non-final statuses. However, it does not mention when not to use the tool or name alternative tools.

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 destructiveHint=true and idempotentHint=false, and the description adds real substance beyond them: the exact persistence target (.agentpack/usage/<task id>.json), that re-linking a file replaces its prior selection, that traced sessions are always included, and that session numbers can shift between calls so ids are safer. This is precisely the mutation-behavior detail annotations cannot express.

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 default no-flag behavior and the write target, and nearly every clause carries decision-relevant information. The middle sentences are dense run-ons (client/file/turns, remove) that could be split for faster scanning.

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 10-parameter, zero-required, destructive mutation tool with no output schema, the description covers the operating modes, defaults, exclusivity rules, and side effects well. It is slightly thin on what the candidate listing contains and on the phase/task defaulting behavior, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is already 90%, so the baseline is 3, but the description adds mode-selection meaning the schema lacks: remove is exclusive with other link options, turns applies to file, and note/coverage are coupled. It stops short of documenting every parameter's edge cases (e.g. task default, phase default main).

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 (link session transcripts to a Task Passport) and the downstream payoff (usage_report can report the task by id). The listing-vs-linking mode split makes it clearly distinguishable from siblings like usage_report and record_source.

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 clear operational context: with no pick/file/remove/coverage it only lists candidates, and the agent is told to show candidates to the user and link only what they confirm. It does not explicitly name an alternative tool or say when not to use this one, so it falls just short of the top band.

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 and openWorldHint=false already covering the safety profile, the description adds substantial context: no collection/rates/ledger writes, overhead estimation caveats, subagent counting semantics, and that monetary snapshots are unavailable for filtered ranges. This is rich behavioral disclosure well beyond the 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?

The purpose is front-loaded, but the body is a dense run-on block of semicolon-chained clauses mixing modes, counting rules, and caveats. Information is present but not well segmented, forcing the reader to parse a single sprawling paragraph.

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 9-parameter tool with a complex oneOf schema and no output schema, the description covers the invocation modes, counting semantics, and monetary caveats needed to call it correctly. It is fairly complete, though the mode interactions could be crisper.

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 already high (89%), so the baseline is 3, but the description adds real meaning: 'task' as a Task Passport id (omit for current), 'turns' accepting N, N: or N:M in a single file, and the interplay between task/manifest/client+files modes. It explains parameter combinations the schema's oneOf only implies.

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 opening sentence states a specific verb and resource ('Report local Codex/Claude Code usage') and a triggering condition. It also names the related sibling usage_link, but does not clearly distinguish itself from the many other task/source-reporting siblings. A clear purpose, but sibling differentiation is only partial.

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

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

It gives explicit context ('when the user asks about work usage') and describes the three invocation modes (task, manifest, or client/files) plus when to follow up with usage_link. It stops short of stating when NOT to use this versus alternatives like source_status, but the guidance is solid.

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