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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds substantially beyond them: no arguments, writes nothing, never echoes another call's arguments, and every fact is observed at call time with no heartbeat or cached verdict. It also discloses the degraded-path behavior (full conditions plus remediation), which is not derivable from 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?

Front-loaded with the question it answers and the return shape, then triggers, then guarantees, then alternatives — a sensible order with no filler. The middle sentence is long and clause-stacked, which slightly hurts scanability, but every clause carries real 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?

Covers the return format, the degraded case and remediation, purity guarantees, and sibling disambiguation — everything an agent needs to decide and call correctly, so nothing further is required of 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?

There are zero parameters, so the baseline is 4 and the schema is trivially complete. The description reinforces this by stating 'takes no arguments,' which is consistent and mildly useful but adds no semantics beyond the empty schema.

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

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

Opens with a direct question the tool answers ('Is bantamkit working, and which bantamkit?') and immediately specifies the exact returned form (`bantamkit Active 🟢` first line, version, build_id, surfaces, memory store, event log). It explicitly contrasts itself with build_identity (build_id only) and shiftwork_status (a job, not the server), so an agent can distinguish it from siblings 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?

Gives three concrete trigger conditions: the user asks whether the server is alive, a bantamkit tool answered oddly and the server may be the cause, or a reply carries a `bantamkit degraded` footer. It also names the alternatives and when to prefer them (build_identity for fingerprint comparison, shiftwork_status for jobs), leaving nothing 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/openWorldHint already covering safety, the description still adds real context: no arguments, reads no state, and a precise unavailable-value contract (`{"unavailable": "<reason>"}` plus an `unavailable` list) that prevents an agent from mistaking a sentinel for a genuine value. That is disclosure beyond what annotations or 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?

Front-loaded with what it returns before the when-to-use rationale, and every sentence carries information. Slightly dense — the version-vs-build argument is restated across clauses — but no filler 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?

An output schema exists, yet the description still tells the agent the key field name and the unavailable-sentinel convention, plus the comparison workflow. For a no-argument read tool this is complete: an agent knows what it gets, what it means, and what to do with 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?

Zero-parameter tool, so baseline is 4; the description confirms 'takes no arguments,' which is consistent with the empty schema. There is nothing further to disambiguate.

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 — returns `build_id`, a content fingerprint of the running source and asset pack — with enough detail that its uniqueness versus `bantamkit_status` is immediately legible. The contrast between version strings and build fingerprints clarifies what the tool actually reports.

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 an explicit trigger ('when one MCP server name may resolve to more than one install'), a decision rule (same version != same build; compare `build_id`), and a named alternative (`bantamkit_status` for health or store binding, which embeds this fingerprint). Both when-to-use and when-not-to-use are covered.

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?

Adds substantial context beyond the annotations: what actually moves, that nothing is deleted and archived facts remain on disk and are still visible to memory_recall with include_archived, that restoration is an operator CLI action rather than a tool, and that read-only grants and the profile layer are untouched. The 'Nothing is deleted' line could read as tension with destructiveHint=true, but it is a clarification of what 'destructive' means here (index removal, recoverable archive) rather than a contradiction.

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 trigger and the action, and each subsequent clause adds a distinct, load-bearing fact (returns, recoverability, operator restore, scope exclusions, sibling differentiation). It is dense and parenthetical-heavy, which costs a little readability, but no sentence is 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 annotations, a fully documented single parameter, and an output schema, the description covers what an agent still needs: when to call, what happens under budget, what is returned ('every archived name with its type and description'), and that recovery is out-of-band. Nothing material is missing.

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

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

The description never mentions the single parameter, but schema description coverage is 100% and the schema's `reserve` description is unusually thorough, including the default formula and a worked numeric example. Baseline 3 applies since the schema carries the parameter meaning.

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

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

States a specific verb (compact/archive) and resource (the writable project memory store), names the exact trigger ('when memory_save was refused for budget'), and describes the selection rule ('stalest facts ... until a fact as large as the biggest one kept will fit'). It also pre-empts the nearest sibling by declaring 'It is not the pass for ... memory_dream.'

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 the precise usage sequence ('Call it after a budget refusal, then retry the save'), the negative case ('calling it under budget archives nothing and says so'), and the explicit alternative for a different problem ('that is memory_dream'). Nothing about when to reach for this tool 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: names the survivorship rule (project layer wins, profile copy moves to archive/), asserts nothing is deleted, states the out-of-band recovery path (bantamkit-memory restore <name>), and flags the blast radius that the archived copy stops answering for every other project on the machine. This is consistent with destructiveHint=true while clarifying that 'destructive' here means archive-and-move, not deletion.

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 verb and the core rule, and every clause carries operational content. It is nonetheless dense and long for a one-boolean tool, with some rhetorical framing ('never a winner-takes-all', 'what it buys is one copy of a ruling instead of two') that could be trimmed.

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 an output schema present, return values need not be explained, and the description covers everything else an agent needs: default behavior, safety impact, recovery route, sibling alternatives, and the reason the merge is done at all. Nothing material is missing for a destructive one-parameter 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% and the single dry_run parameter is fully described there, so the baseline applies. The description still adds workflow meaning — that the default is a preview, that true performs all reads and merges but writes nothing, and that the agent should call twice (preview then apply).

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: consolidating memories held by the project layer and machine-wide profile layer under the same name, then reporting what changed. It spells out the three resolution outcomes (byte-identical collapse, divergent union, relative-date annotation) and names the surviving location, so an agent knows precisely what the operation does.

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

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

Explicitly routes away from siblings: 'For room in the index call memory_compact instead; for the facts themselves, memory_recall.' It also gives the required call sequence — read the plan first, then re-call with dry_run false — and warns that the default dry run exists because the profile store is machine-wide.

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 by disclosing all-or-nothing validation (the first bad item refuses the whole call), the specific rejection reasons, that no fact files are modified, that queries live in a per-layer sidecar keyed to fact content, and the consequence that an edited fact is re-listed as missing. It also states the batch cap of 10 facts and what the listing 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?

Front-loads the what and when, then the write mode and constraints; every clause is informative. It is a single long run-on paragraph with an awkward opening clause and some repetition of limits already in the schema, which costs readability.

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?

An output schema exists, yet the description still tells the agent what the listing returns (layer, name, description, excerpt, instructions, `remaining`), plus the validation failure modes and the sidecar lifecycle. Nothing needed to call it correctly in either mode 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 the baseline is 3; the description still adds meaning the schema does not, such as the 10-fact listing cap, the fact that the listing includes body excerpts and `remaining`, and the semantics of `queries: []` as removal. It restates some limits (8 queries, 200 chars) already in the schema, so it is additive but not fully non-redundant.

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

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

Names a specific verb pair (write / list) and a precise resource (likely-prompt queries attached to saved facts), and explains the concept in-line: the prompts a user would type when that fact is what they need. It explicitly contrasts itself with the sibling memory_save, so an agent can route between them without opening either 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 trigger conditions: call with {} at the end of a session that saved facts, or when bantamkit_status reports `queries: n of m facts` with n below m; then call with {facts: [...]} to store results. It also names the alternative path (memory_save takes `queries` directly for a fact being saved now) and scopes this tool to facts already on disk.

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 readOnlyHint=false, and the description explains why: every hit appends to the usage ledger and old-format project fact files may be rewritten once, both best-effort. It also discloses layer read order, minimum result behavior, exact-name behavior, and that unreadable fact files are named rather than silently skipped.

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

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

The description is front-loaded with purpose and usage, and nearly every sentence carries useful behavioral detail. It is dense and long, with semicolon-heavy clauses, but not padded with empty 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?

Given five optional parameters, an output schema, and annotations, the description covers timing, alternatives, side effects, read order, result rules, and failure handling. Nothing important for correct invocation appears to be 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 the schema already documents all five parameters. The description still adds cross-parameter meaning: `file` supersedes `query`, exact fact-name queries return that fact alone, `outcome: error` filters to recorded failures, and `k` is floored by the store 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 and resource: search persistent memory for facts saved by a past session. It also distinguishes itself from memory_save and memory_compact/memory_dream, and explicitly says it never changes what a fact says.

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 guidance: before starting work resembling past work, and when the user refers to something decided earlier. It names alternatives for saving and tidying, and explains using `file` instead of `query`.

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: it enumerates the three refusal modes each with their remedy (duplicate description, name normalisation collision, index byte budget), states where the write lands (.bantamkit/memory, never profile or read-only grant), and notes the usage-ledger append. It also explains that a re-save replaces in place, which gives meaning to destructiveHint=true rather than 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 core instruction and the exclusion rule are front-loaded in the first two sentences, which is the right order. The remainder is dense and clause-heavy (nested parentheticals around the refusal cases), so it is efficient for its complexity but occasionally hard to parse in one pass.

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 mutation tool with an output schema, this covers everything the agent needs: scope, exclusions, failure modes with remedies, storage destination, replacement semantics, and lifecycle via status/outcome. Return values are already covered by the output schema, so nothing material 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 the baseline is 3, but the description adds genuine semantics on top: re-saving under the EXACT name replaces in place, renaming to force a copy is refused, and `status: done` closes a project fact while nothing archives. These are behavioural consequences of specific parameter values that the schema descriptions alone do not fully convey.

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 ('Save ONE durable fact to persistent memory') and immediately bounds the scope with examples of what counts. It also names the complementary siblings (memory_recall for finding, memory_compact for freeing room), so an agent can place it among its neighbours 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?

Explicitly says when NOT to use it ('never for anything derivable from the repo, git history or docs, nor for one-off state of this conversation') and routes to the right alternatives: memory_recall to find, re-saving under the exact name to change, memory_compact to free space. That is the full when/when-not/alternative triad.

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=false and destructiveHint=false, and the description explains exactly why: 'on result=brief, and only then, one line {event: brief, ts, unit, role} appended to <checkpoint>.log.jsonl — best-effort' plus 'The checkpoint file itself is never modified' and 'It never moves plan.cursor'. That is genuine context beyond the annotations, including failure tolerance of the log write. It stops short of describing concurrency behavior or ordering guarantees across parallel clock-ins.

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 well: purpose and return shape land in the first sentence. But the body collapses into a dense run-on enumerating refusal strings and outcome names ('escalate', 'success', 'error') in a single paragraph, mixing guidance, error catalogs, and write semantics. It is informative rather than wasteful, but a bulleted outcome list would carry the same content with far less parsing cost.

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 stateful tool that reads a checkpoint and appends a log, the description covers preconditions, all outcome variants, side effects, and non-effects (cursor untouched, checkpoint unmodified), and it points at docs/shiftwork.md for depth. Even though an output schema exists, the inline brief and refusal shapes make the contract unambiguous.

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 resolution semantics the schema only implies: 'The unit briefed is plan.cursor, or `unit_id` when given; either way it must be in shiftwork_plan's `ready`', including what happens for a done/dropped cursor or a dependent cursor. The `checkpoint` parameter adds nothing beyond the schema, but the unit selection logic is meaningfully elaborated.

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 plus the exact payload: 'return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim.' It then names the two siblings it must not be confused with (shiftwork_plan for the `ready` batch, shiftwork_clock_out for unit completion), so an agent can route correctly 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?

Gives explicit timing ('Call it once per unit, right before spawning'), an explicit alternative for the multi-unit case ('use shiftwork_plan first to see the `ready` batch when several units are to run at once'), and an explicit exclusion ('shiftwork_clock_out, not this tool, when a unit finishes'). It also states the precondition that the target unit must appear in shiftwork_plan's `ready`.

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 mark this as a non-read-only, destructive, non-idempotent operation, and the description adds substantial context: schema validation before a single atomic write, failure semantics with {"result": "error", "reason": ...}, cursor advancement rules, history-ring behavior, attempts truncation, and accounting gates. This gives the agent a clear picture of what is mutated and what happens on 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?

The description is dense and long, but it is front-loaded with the core action and every sentence carries operational detail for a complex 10-parameter mutation tool. It could be split into clearer sections, but it avoids filler.

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

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

Given the complexity of the tool, the nested schema, the annotations, and the presence of an output schema, the description is complete enough for correct invocation. It covers the atomic write model, required arguments, cursor rules, accounting constraints, follow-up creation, agreements, and role/model validation.

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 in detail. The description still adds useful cross-parameter meaning, especially the required handoff_patch/history_entry contract, cursor behavior, accounting-line contents, follow_ups and agreements effects, and the job.roles model gate.

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 first sentence states a specific verb and resource: clock out a shift-work unit and record that it finished, then enumerates the concrete mutation effects. It explicitly distinguishes the sibling tools by saying shiftwork_clock_in briefs, this tool closes, and shiftwork_status reads what both wrote.

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 exactly when to call it: once per unit after its agent returns. It also names the related alternative tools and explains the unit_id prerequisite, including which units are accepted and which are refused.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world write, and the description adds substantial detail beyond them. It explains the dry-run default, write:true temp-file-and-rename behavior under a lock, refusal on existing checkpoints or differing briefs, partial-failure reporting in `written`, and that it never runs git, verify, or reads the working tree. No contradiction with 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 front-loaded with purpose and usage, and nearly every sentence carries behavioral or validation detail rather than filler. It is dense as one long paragraph; splitting write semantics and validation into short sections would improve scanability without adding length.

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 eight-parameter tool with nested ticket objects, an output schema, and write behavior, the description covers defaults, refusal shape, write atomicity, schema validation, and what the tool does not touch. An agent has enough information to invoke it correctly without opening the schema.

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

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

Although schema coverage is 100%, the description adds validation and relational meaning beyond the schema: every ticket needs non-empty id, title, role, verify, data_shape, and brief, with the first missing one refused by name. It also explains role checks against job.roles, brief_path composition, cursor derivation, and the dry-run default for `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 and resource: turn tickets into a new job consisting of a schema-valid checkpoint plus one brief file per ticket. It names the exact stage of the shift-work loop and distinguishes itself from planner edits, clock_out follow_ups, and the read-only work_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?

Explicitly says to call it once, when a job's tickets are settled and before the first shiftwork_clock_in. It also states when not to use it (a job in progress) and names the alternatives for those cases: the planner's edit, shiftwork_clock_out's follow_ups, and work_plan for read-only batches.

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 and openWorldHint=false; the description adds substantial behavior beyond that: never moves plan.cursor, never writes, refusals are structured rather than exceptions, terminal units are treated as satisfied, and a bad `touches` path or invalid `reviews` reference is refused with a named sentence. Output fields (`ready`, `width`, `held`, `budget`) and their absence conditions are also 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?

The purpose and the routing guidance to siblings are front-loaded in the first two sentences, which is exactly right. It is a long, dense block afterward, and a few clauses (repeated refusal-by-reference to work_plan's and shiftwork_status's sentences) could be tightened, but nearly every sentence carries operational 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 read-only planner with one parameter and an output schema, the description covers everything an agent needs: batch composition rules, ordering, cursor behavior, empty-ready semantics, holds from path conflicts, review validation, and budget output. Nothing material is left 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 coverage is 100% and the single `checkpoint` parameter is well documented in the schema, so the baseline would be 3. The description adds real meaning by explaining which part of that file is consumed (plan.units, depends_on, touches, reviews, job.budget) and that cursor is echoed unchanged.

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

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

Names a specific verb and resource: computes which units of a checkpoint may run now and in what waves, derived read-only from the depends_on graph. It immediately distinguishes itself from shiftwork_status and work_plan, so an agent can route 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?

Gives an explicit call point ("Call it before dispatching a wave") and names both alternatives with the condition that selects each: shiftwork_status for progress counts only, work_plan when the graph is supplied as `nodes` rather than read from disk. It also explains the downstream dependency on shiftwork_clock_in and clock-out.

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 readOnly/openWorld annotations, it discloses that every fact is read fresh on this call (no caching), that invalid or missing checkpoints return a structured {"result": "error", "reason": ...} instead of a partial summary, and that it opens only the checkpoint (plus the archive dir when search is given) and writes nothing, not even a log line.

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?

Content is front-loaded with purpose, then usage, exclusions, behavior, and side effects, and nearly every clause carries information. It is dense and long-winded in places (the error/refusal sentence and the search aside), slightly hurting scanability, but nothing is 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 status tool with an output schema, the description covers everything an agent needs: what is returned, when to call it, which siblings to use instead, failure semantics, and side effects. No material gap remains.

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 fully documented in the schema. The description's search sentence largely restates the schema text, adding only the note about opening the archive directory; with the schema doing the heavy lifting, 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 ('where ONE checkpoint file stands') and enumerates the exact facts returned (units by status, plan.cursor unit, handoff.open_questions count, last history entry). It explicitly demarcates itself from siblings: shiftwork_plan for runnable units and bantamkit_status for the server.

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 an explicit trigger ('Call it first when resuming a job or answering where is job X; it is the cheap read before any clock-in') plus explicit exclusions routed to named alternatives. Nothing about when to pick this versus shiftwork_plan or bantamkit_status 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 mark it read-only and closed-world, and the description adds substantial context beyond that: the exact walk pattern, the JSON keys returned, the degraded-server footer key, and the four refusal conditions (unknown check, negative budget, empty/missing/file root). It stops short of describing pagination or size limits, but the disclosure is far richer than the annotations alone.

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?

Long, but front-loaded with purpose and dense with non-redundant detail (findings kinds, omissions accounting, refusal rules), each sentence carrying weight. Some of the output-schema content (`findings`, `omissions` shapes) is repeated, which trims the score from 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 a 6-parameter tool with nested objects and an output schema, this covers everything: what is scanned, what each optional input contributes, how degraded servers signal themselves, and that refusals are total rather than partial. Nothing an agent needs to call 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 the baseline is 3, but the description supplies genuine semantics the schema does not: why omitting `enabled` inflates the bill (the cache holds disabled plugins), and that `versions` exists specifically to fix byte-order misresolution such as `10.0.0` against `9.0.0`. These are caller-facing semantic hints, not restatements.

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 — pricing the skill catalogue and naming collisions — with a clear mechanism (the `description:` frontmatter being the standing bill). No sibling tool covers anything similar, so differentiation is implicit but 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 explicit trigger conditions: 'Call it before adding or retiring a skill, or when two skills keep firing on the same phrase.' This tells the agent when the tool is worth invoking rather than leaving it 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 only cover readOnly/openWorld; the description adds substantial behavior beyond them: per-requestId dedupe spanning the whole walk, duplicate-request omissions, subagent cost attributed to the parent as sidechain_requests, the invariant lines = requests + omission counts, the bantamkit_degraded footer, and the four explicit refusal cases. This is far more than the annotations convey.

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

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

Purpose, scoping rule, and misuse warning are front-loaded and every sentence carries information. It is dense and jargon-heavy (bantamkit_degraded, relpath:line omission format), which pushes against readability, but there is essentially no filler to cut.

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 single-input aggregation tool with an output schema present, the definition covers invocation constraints, edge cases, invariants, and failure modes; an agent has everything needed to call it correctly and interpret the result.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema — the one-project-per-call constraint on `root`, that `prices` is only consulted when `model` is set, and that `{"unavailable": ...}` is the normal cost answer rather than an error.

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

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

Opens with a specific verb+resource framing — reporting what a session cost from the host's own transcripts — and names the exact artifacts it walks (*.jsonl under ~/.claude/projects). No sibling tool does anything similar, and the agent can tell immediately what this produces.

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 trigger ('Call it to answer "what did this work cost"'), an explicit scoping rule ('Point root at ONE project's slug directory'), and an explicit when-not with the consequence ('there is no time window or summary mode, so a whole-corpus call ... blows the host's tool-result cap').

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 cover read-only and closed-world; the description goes far beyond them with the retry contract (hand `feedback` back, retry), feedback truncation at 200 characters, null-on-success, $ref confinement with remote refs refused and never fetched, and a 500 ms shared regex budget that yields a refusal rather than partial results. The closing "reads nothing but its two arguments and writes nothing" reinforces the annotation rather than 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?

Dense single paragraph but front-loaded: purpose and return shape come first, then routing, then argument conventions, then edge cases. Every sentence carries information an agent needs to call or interpret the tool; nothing is decorative.

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-arg validator with an output schema and closed-world annotations, the description covers the retry loop, the failure modes (refused remote refs, regex timeout), and the input acceptance rules. No gap remains that would cause a misinvocation.

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?

Despite 100% schema coverage, the description adds real semantics the schema lacks: the extraction order for `output` (bare JSON value, else first fenced block, else first object/array), which drafts `$schema` accepts and that 2020-12 is the default, and the allowed `$ref` forms. These change how an agent must shape its arguments.

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

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

Opens with a specific verb+resource ("Validate candidate output text against a JSON Schema") and immediately states the answer shape {valid, feedback}. It also distinguishes itself from the sibling checkpoint tools, so an agent can route correctly 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 an explicit trigger ("Use it on any JSON a model produced before acting on it") and an explicit exclusion with named alternatives ("for a shift-work checkpoint call shiftwork_status or shiftwork_clock_in instead"). Both the when and the when-not are present.

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 say readOnlyHint/openWorldHint=false, and the description reinforces rather than contradicts them ('no file opened, no path taken, nothing mutated'). Beyond that it discloses the determinism contract (priority then input order, byte-identical across implementations), the `held` output with its exact shape and the condition under which it is absent, and an ordered list of five refusals with their message shapes — behavior an agent cannot infer from annotations alone.

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?

Purpose and purity are front-loaded, and nearly every clause carries operative information (batching rule, tie-break order, refusal order, held semantics). It is dense to the point of being a wall of text, and it explains `sequence`/`width` return values despite an output schema existing, which is the main 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 a single nested-graph parameter and a complex batching contract, the description covers ordering, fan-out, contention handling, and all failure modes an agent could hit. The output schema carries the return shape, so the extra prose about `sequence`/`width` is surplus rather than a 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 field-level docs are already in the schema; the description still adds real meaning by stating that `depends_on` encodes logical order rather than file contention, and that `touches` lists paths the node will WRITE, which explains why the two fields interact. It also specifies validation consequences (invalid ids/paths named by position, never coerced) that go beyond the schema's types.

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

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

Opens with a specific verb and resource — turn a dependency graph into parallel batches — and immediately bounds it as 'pure computation over `nodes`'. It names the sibling it is not (shiftwork_plan) and states the distinguishing condition (graph in hand vs. checkpoint on disk), so an agent can route between them 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?

Explicit when-to-use: 'Use it when the graph is in your hands (tasks with depends_on)', paired with an explicit alternative and its trigger ('use shiftwork_plan when the graph is a shift-work checkpoint on disk'). It also preempts a likely misuse by declaring empty `nodes` an answer rather than a refusal.

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