Weft

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description largely restates that ("Idempotent... is a no-op"), which duplicates structured data. It does add the concrete outcome of a repeat call, but omits auth requirements, whether the sprint must be active, and behavior on completed/archived sprints.

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 usage trigger and followed by a short behavioral note. No waste, no redundancy in structure.

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 two-parameter mutation with no output schema, the description covers intent and idempotency but leaves preconditions (sprint state, permissions) and error behavior unstated. Adequate but with clear gaps given the mutation nature of 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 description coverage is 0% and the description says nothing about the two required parameters (taskId, sprintId) or their UUID format constraints. Unlike a zero-parameter tool, this needs compensation and provides none beyond the parameter names being self-explanatory.

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: pulling an existing task into a sprint. An agent can distinguish this from create_task (which creates new work) without opening the schema. It does not explicitly differentiate from the inverse sibling remove_task_from_sprint, 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?

"Use this when the user wants to pull an existing task into a sprint" is a trigger condition, but it only restates the purpose. No alternatives are named (remove_task_from_sprint for the inverse, move_task for reordering/cross-sprint moves), so the agent must infer boundaries from sibling names alone.

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 and idempotentHint=true, so the safety profile is known, yet the description adds substantial context: archived tasks are never deleted and remain searchable and visible in sprint history, there is no count/selection and no undo on this surface, and a second call is a no-op. It also prescribes confirming with the user first.

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 condition, then consequences, then the confirmation requirement. Every sentence carries distinct information (scope, recoverability, alternatives, idempotence) with no filler.

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

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

For a zero-parameter, no-output-schema mutation, the description covers everything an agent needs: when to invoke, what is affected, what is reversible, alternatives, and the confirmation requirement. Nothing material is left unspecified.

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

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

Zero parameters, so the baseline is 4. The description does add one useful semantic point the empty schema cannot convey — it operates on the WHOLE column in a single call with no count — which clarifies why no parameters exist, but it goes no further than that.

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 (archive) and resource (every task in the Done column), and explicitly distinguishes itself from complete_sprint (which archives a sprint's tasks automatically) and restore_task (which works on the trash, not the archive). An agent can select it 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 concrete user phrasings that trigger it ('archive everything in Done', 'clean up the board'), names the alternative (complete_sprint already covers sprint-scoped archiving; restore_task covers trash), and states an explicit exclusion: never call it to tidy up on your own initiative.

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 say it is a non-read-only, non-destructive, closed-world write. The description adds genuinely new behavioral facts: single database transaction with all-or-nothing semantics, cheaper on the monthly AI-call quota, and deterministic ordering (tasks land in each column in array order, after existing tasks). These go well beyond what the annotations disclose.

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 trigger condition, then atomicity, then the quota rationale, then the column/sprint mechanics. Dense but purposeful; the parenthetical asides are the only mild padding.

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

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

Only one top-level parameter with full schema coverage and no output schema, so little needs explaining. The description covers atomicity, ordering, quota cost, and sprint prerequisites, but says nothing about what the batch returns (IDs created) or how partial-input validation errors surface despite the all-or-nothing claim.

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 3 baseline is already met by structured fields. The description still adds meaning for two key fields: 'column' accepts either a semantic value or a column name, and 'sprintId' must come from a sprint created beforehand. No guidance on dueAt/startAt/assignee beyond what the schema already documents.

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 ('import many tasks at once', 'creates the whole batch') and explicitly contrasts with the sibling create_task ('instead of N create_task calls'). An agent can distinguish this from create_task 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 (CSV/JSON export from Linear, Jira, Notion, Trello, or any list of 3+ tasks from the conversation) and names the alternative (N create_task calls). It also supplies a prerequisite workflow: create sprints with create_sprint first if the export references cycles/iterations.

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 the description enriches that with concrete consequences: finished tasks are archived to sprint history, leave the Done column but stay searchable, unfinished tasks remain, and the action 'cannot be undone via MCP.' This is exactly the behavioral context an agent needs before a destructive mutation.

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

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

Three tight sentences, front-loaded with the trigger, then the effect, then the irreversibility warning. No filler; every sentence adds decision-relevant 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 destructive one-param mutation with no output schema, the description covers trigger, effect on both finished and unfinished tasks, reversibility, and an ambiguity guard. Nothing needed 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?

There is one required param (id) with 0% schema description coverage, and the description never explains it. The sprint id is strongly implied by the action and the schema supplies the UUID format, so the gap is tolerable but real.

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

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

The description states a specific verb+resource: 'Marks the sprint complete and archives its finished tasks.' It also cycles through what happens to finished and unfinished tasks, which distinguishes it clearly from siblings like complete_task and archive_done_tasks.

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?

'Use this when the user has finished a sprint and wants to wrap it up (e.g. close this sprint)' gives a clear triggering condition and adds a caution to confirm on ambiguous intent. It doesn't name an explicit alternative tool, but the trigger phrasing is unambiguous.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds substantial non-obvious behavior: the call never fails for missing evidence, evidence is recorded regardless, needs-user tasks are routed to a queue rather than Done, and the server executes verification-plan checks server-side and blocking failures keep the task out of Done. This is exactly the kind of behavioral context annotations cannot carry.

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 most important instruction (when to call) is front-loaded and every sentence carries information. It is a dense single block with some long compound sentences, so structure could be improved, but there is little waste.

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

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

For a mutation tool with 11 params and no output schema, the description covers the safety/routing model, the evidence model, the verification-check execution, and the failure semantics. An agent has everything it needs to call correctly and to interpret the outcome.

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 goes beyond the schema by defining how key params behave: outcome as 1-3 sentences of what was done and where the result lives, artifacts as independently checkable evidence, and nextStep as the sentence shown above the user's Accept button. It adds real meaning over the structured field descriptions.

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

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

The description states a specific verb and resource ('work on a task is actually finished', task moves to Done) and distinguishes the terminal state-change from sibling operations like report_progress and request_input by naming the routing consequences. An agent can tell this is the completion call without opening the schema.

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

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

Explicit when-to-use ('Call this when the work on a task is actually finished') plus a hard prohibition ('Never report a task as done to the user without calling it') and an implicit when-not ('report progress in note/outcome instead'). It stops short of naming sibling tools like report_progress or request_input as the alternative for non-finished work.

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 annotations already covering the safety profile (write, non-destructive, non-open-world), the description adds real behavioral context: the name must be unique per board, color defaults to a rotating palette pick, and url drives the favicon on task cards. It omits what happens on a duplicate-name failure, which is the main remaining gap.

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

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

Three sentences, front-loaded with the usage trigger, each carrying distinct information (when to use, name constraint, color/url behavior). No filler 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 3-param create tool with no output schema and annotations carrying the safety profile, the description covers usage, the key constraint, and default/side-effect behavior. It does not describe the return payload or error handling, which is minor given no output schema is declared.

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 67%, and the description compensates for the uncovered name parameter by stating the per-board uniqueness rule, plus it clarifies the color default behavior (rotating palette) and the url's purpose. This meaningfully extends what the schema documents (enum list, uri format).

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

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

The description states the resource ('a new project context') and, together with the name/title, makes the create action unambiguous. It implicitly distinguishes from siblings like create_task/create_sprint by naming the project resource, but it never explicitly contrasts itself with them or with update_project.

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

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

It gives a clear when-to-use trigger with a concrete example utterance ('add a project for Organicus'), which is stronger than most. It does not state exclusions (e.g. use update_project for existing projects) or any prerequisites, so it stops 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?

Annotations only declare readOnly=false, destructive=false, openWorld=false, so the description adds real value by disclosing that the sprint is created in 'planned' state and that tracking requires a separate start_sprint call. It omits permissions/auth requirements, which is the only notable gap.

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

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

Three tight sentences, each doing distinct work: trigger, resulting state plus next step, and synonym disambiguation. No filler and the usage condition is front-loaded.

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

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

The lifecycle behavior is well covered and annotations carry the safety profile, but with 0% schema description coverage on four parameters and no output schema, the description leaves the caller guessing about field meaning and requiredness. Adequate, not complete.

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

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

Schema description coverage is 0% for four parameters, and the description never explains name, goal, startsAt, or endsAt — not even that name is the sole required field or how the date bounds behave. It cannot lean on the schema here, so the gap is significant.

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 ('Creates the sprint') and pins down the resulting state ('planned'), which distinguishes it from start_sprint and complete_sprint in the sibling list. An agent can select it without opening the schema.

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

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

Explicitly gives the trigger condition ('when the user wants to plan a new sprint'), names the follow-up alternative ('call start_sprint separately when ready to begin tracking'), and resolves vocabulary ambiguity (focus/sprint/cycle/iteration/week). Nothing is left to inference.

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

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

Annotations already declare this is a non-read-only, non-destructive mutation. The description adds useful behavioral defaults beyond the annotations: omitted columnId goes to Backlog, and priority defaults to medium with urgency heuristics. It still omits permissions, response shape, and creation 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 efficient sentences, front-loads the invocation trigger, then covers notable defaults. 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?

For a 13-parameter tool with nested verification and many siblings, the description covers basic invocation and two defaults but omits advanced parameters, sibling routing, and return-value expectations. The schema carries much of the complex parameter detail, but the description is not complete for this level of 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?

The description adds meaning for columnId and priority beyond the schema, including default routing and a heuristic for priority selection. However, with 13 parameters and only 54% schema description coverage, several parameters such as sprintId, description, and estimateMinutes are not explained in either place.

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

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

The description states a specific action (capturing/creating a task) and gives concrete user trigger phrases such as 'add a task' and 'remind me to'. It does not explicitly distinguish this from siblings like bulk_create_tasks or add_task_to_sprint, so it is clear but not fully differentiated.

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

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

It gives explicit when-to-use guidance via trigger phrases and adds a priority heuristic for urgency terms. It does not state when not to use it or route multi-task/sprint-specific cases to sibling tools, so it is strong but incomplete.

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, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description earns credit by disclosing the return payload (title, full text, source url, structured metadata), which matters because there is no output schema. It omits failure behavior for a malformed or non-existent id, which is the remaining gap for a lookup tool.

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

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

Two sentences with no filler; the usage trigger is front-loaded and the second sentence carries only the input contract and the return contents. Nothing could be removed without losing information an agent needs.

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

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

One required, fully documented parameter, no output schema (and the description compensates by describing the return fields), and a clear upstream dependency on `search`. For a tool of this complexity, an agent has everything it needs to call it correctly.

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

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

Schema description coverage is 100% and the schema itself carries the regex pattern and the `task:<uuid>` / `sprint:<uuid>` example. The description restates the same provenance ("prefixed id returned by `search`") without adding format, escape, or edge-case detail, so the schema is doing the heavy lifting and the baseline 3 applies.

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

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

States a specific action (retrieve the full content of a search result) and the resource (a Weft item identified by a prefixed id), then enumerates what comes back: title, full text representation, source url, structured metadata. It explicitly positions itself relative to the sibling `search`, so an agent can tell the two apart 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?

"Use this when you need the full content of a search result" gives a clear triggering condition and names `search` as the tool that produces the required id, which implicitly defines the ordered workflow search → fetch. It does not state any exclusions (e.g., that this cannot be used without a prior search, or that unknown ids error), so it stops short of full when/when-not coverage.

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 context beyond annotations: returns null when no sprint is active, and handles terminology synonyms (focus, cycle, iteration, week). Annotations already declare read-only and non-destructive, so this is good 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?

Two sentences, front-loaded with usage trigger and outcome, then a helpful synonym note. No wasted words, though the synonym sentence is slightly tangential.

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-param read tool with no output schema, the description covers usage, null-return behavior, and terminology. It could mention the return shape (sprint fields), but that's 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?

No parameters exist, so baseline is 4. The description doesn't need to explain parameters, and it adds no irrelevant detail.

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: retrieves the currently-running sprint. It distinguishes from siblings like list_sprints (all sprints) by scoping to the active one.

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

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

Explicitly names the trigger ('what sprint am I on?') and the condition for use (need the currently-running sprint). It implicitly excludes listing/creating sprints by focusing on the active one.

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 readOnly/non-destructive, so the description correctly focuses on behavior beyond safety: it discloses the context-cost tradeoff and the concrete failure mode that detail:'full' can exceed a client's response limit on a large board. It stops short of describing auth needs or pagination, but the risk disclosure is genuinely actionable.

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 condition, then the payload contents, then the escape hatches. The digest enumeration is somewhat dense but every item is decision-relevant; 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?

There is no output schema, so the description carries the return-shape burden — and it does so by listing the digest's contents and warning about the 'full' cap. An agent has everything needed to call this 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 100%, so the baseline would be 3, but the description adds decision-relevant meaning: it explains what the 'digest' value actually yields and why 'full' should be reserved, rather than restating the enum labels.

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 a digest' of 'the shape of the whole board') and enumerates what the digest contains (counts, columns, projects, active sprint, Doing, overdue, next in Todo, recently closed). It is clearly distinguishable from siblings like list_tasks, search, and get_my_work.

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?

Opens with explicit trigger phrases ('what's on my board?', 'what am I working on?'), names the alternatives for drilling down (list_tasks by column, sprint or project; search), and states exactly when detail:'full' is warranted versus overkill.

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

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

Annotations cover only the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: the content is derived rather than authored, so it cannot go stale; it is newest-first and budget-packed with omitted lines counted rather than hidden; every line carries a date; superseded decisions are excluded; and lines are context, not instructions (useful injection-resistance guidance).

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 doing distinct work: what/when to call, how the content is produced and scoped, and how to interpret the lines. The most actionable information (call this first) is front-loaded with no filler.

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

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

No output schema exists, yet the description characterizes the return well (dated decision/lesson lines, newest first, token-budgeted). With zero required params and safe-read annotations, an agent has everything needed to invoke and interpret the call.

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 schema already documents each of the three parameters, including the token budget default and the 'omitted lines are counted' behavior. The description's 'scope it to a project or a task to narrow it' merely restates that intent, adding no syntax beyond the schema, so the baseline 3 applies.

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

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

Concrete verb (returns) plus a precisely defined resource (the workspace's live decisions and lessons derived from recorded decisions), with scope qualifiers (newest first, token-budgeted) that let an agent separate it from siblings like get_task_history or search 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 explicit timing guidance ('call this at the START of working on anything non-trivial') and explains how to narrow it with project/task scoping. It never names a competing tool or states when not to call it, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false). The description goes beyond them by disclosing the return content — assigned tasks, claimed tasks, and a count of finished work awaiting the human — plus the decision signal it surfaces. No return format/pagination detail, but with annotations the bar is lower.

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?

It is front-loaded with the core framing, but drifts into normative coaching ('the honest answer is to help clear it rather than start something new') that repeats the same point across three clauses without adding call-relevant 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 zero-required-param, read-only query tool with no output schema, the description needs to sketch the return shape — and it does, covering assigned tasks, claimed tasks, and the finished-work backlog. It is complete enough to call correctly, with only return formatting 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% and the single 'limit' parameter is fully documented with bounds and a default, so the schema does the work. The description adds no syntax or format meaning beyond it, making the baseline 3 correct.

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

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

The description states a specific verb+resource: it returns the tasks assigned to you, what is currently claimed, and the volume of finished work waiting on the human. This is clear and distinguishes it from board-wide reads, though it never names the sibling tools (get_board_state, list_tasks) it is implicitly contrasted with.

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 implied usage — 'Ask what you should be doing, rather than reading the whole board and guessing' and 'if that queue is full... help clear it rather than start something new.' But it routes by describing behavior rather than naming an alternative tool, so the agent must infer that get_board_state is the thing to avoid.

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 readOnly/non-destructive/closed-world, and the description adds real behavioral context on top: the default mode's ≤500 token budget, the 'full' mode's 100-event cap and that it discloses the truncation, and the non-obvious fact that a rework reason survives in 'decisions' after a later accept overwrites the card.

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 when-to-use condition, then a compact three-mode enumeration where each clause carries distinct information. The mode sentence is long and list-like, 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 no output schema, the description carries the return-value burden and does it well — card, latest receipt, counts, verdicts with reasons, raw journal. Only a minor gap: nothing about ordering or whether results are scoped/paginated beyond the 100-event cap.

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 enum names the three modes, but the description adds meaning the schema cannot: what each mode returns, relative cost, and truncation behavior. That goes beyond baseline 3, though it does not document the id parameter's format (already covered by the schema pattern).

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

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

The description states a specific verb+resource (retrieve what HAPPENED to a task, its history) and immediately distinguishes it from current-state reads with 'not just its current fields'. An agent can separate it from list_tasks/update_task 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 triggering scenarios — before retrying failed work, judging a receipt, answering 'why is this still open?' — plus per-mode selection guidance. It stops short of naming a specific sibling alternative (e.g., 'for current fields use list_tasks'), but the implied contrast is clear.

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=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral detail beyond that: the exact four default columns created and the guarantee that existing columns are left 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?

Two tight sentences: the usage condition and side effect come first, the idempotency caveat second. No filler, and every clause carries information an agent needs.

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

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

For a no-parameter, no-output-schema bootstrap tool, the description covers the trigger, the side effect, and repeat-call behavior. It does not mention whether the caller's permissions or workspace scope matter, which is a minor remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is trivially complete and the description adds no misleading parameter claims.

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 (creates) and resource (the board's default columns) and enumerates exactly what is produced: Backlog, Todo, Doing, Done. This clearly separates it from siblings like get_board_state and list_columns, which read rather than initialize.

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?

"Use this when a brand-new user has no board yet" gives an explicit triggering condition, and the idempotency note tells the agent it need not guard against repeat calls. It does not name an alternative tool, but none is really needed for a zero-argument bootstrap operation.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds one genuine behavioral trait — the results are returned in board order — but says nothing about pagination, filtering, or return shape. With annotations carrying the safety load, this is a modest but real addition.

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

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

Two tight sentences with no filler; usage is front-loaded and the return behavior follows. It is appropriately sized for a trivial zero-param tool. The first sentence mixes usage and purpose slightly, but nothing is wasted.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description supplies enough: what it returns, in what order, and when to reach for it. It could note whether the result is empty when no board exists, but that is 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?

The tool takes zero parameters, so per the baseline no parameter explanation is required. The description correctly implies a no-argument listing operation. Nothing is missing or misleading.

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

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

The description states the specific resource and action ('Returns columns in board order'), so an agent knows this lists board columns. It does not reference a sibling tool for contrast, but no sibling covers columns, so differentiation is not really needed. Clear verb+resource without extra disambiguation.

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 triggers: 'when the user asks about workflow stages' and 'you need column IDs for another call.' That tells the agent both a user-facing and an internal reason to call it. It stops short of naming exclusions or alternatives, which is not critical here.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuine domain semantics beyond that: projects are lightweight contexts and a task belongs to at most one. It omits return shape/pagination, but with annotations carrying the safety profile this is above baseline.

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

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

Two sentences, zero filler, with the primary trigger front-loaded and the parameter hint last. Every clause earns its place.

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

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

For a one-param, read-only list tool with no output schema, the description supplies the domain model (lightweight contexts, single-project membership) an agent needs to reason about results. It could say more about what a project record contains, but that gap is minor given the annotations.

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 parameter is self-documenting ('Include archived projects (default false)'). The description only restates that archived projects exist and are opt-in, adding no syntax or behavior beyond the schema — baseline 3.

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

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

States a specific verb+resource (list projects) and distinguishes itself from the write siblings (create_project, update_project, archive). The added framing — 'you need to know which projects exist before filing tasks into one' — makes the tool's role unmistakable.

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

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

Gives an explicit trigger ('when the user asks about their projects') plus a second motivating use case (pre-flight before filing a task). It does not name a competing alternative (e.g. search or get_context) or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered and the bar is lower. The description still adds real behavior: a hard return cap of 100 sprints and a synonym map (focus/sprint/cycle/iteration/week) that affects how the agent interprets user intent. It does not say what happens when more than 100 exist (truncation vs pagination), which is the one remaining gap.

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

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

Three short sentences, front-loaded with the triggering condition and the routing decision before the limit and vocabulary notes. Every sentence carries distinct, non-redundant 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 zero-parameter, read-only list tool with no output schema, the description supplies the scope, the alternative, the result-size bound and the terminology mapping. Nothing an agent needs in order to call this correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate in the schema. The synonym note adds interpretive value about the domain vocabulary but no additional parameter-level meaning is needed or missing.

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 ('List Sprints' / asks about sprints in general) and explicitly scopes it to past, planned, active and archived states. It also names the sibling it is not for ('For just the running one, prefer get_active_sprint'), so an agent can separate it from get_active_sprint 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 an explicit trigger condition ('when the user asks about sprints in general') plus the exclusion and the named alternative get_active_sprint for the running-sprint case. This is a complete when-to-use/when-not-to-use routing statement.

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/destructiveHint already declaring the safety profile, the description goes further: a 200-result cap with a documented remedy, the non-obvious inclusion of archived ('swept') tasks in sprint-scoped listings, and the semantics of date-range matching (due, starting or running inside the window) plus date ordering. These are behaviors nothing in the annotations or schema discloses.

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

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

Four dense sentences, front-loaded with the trigger condition before the fallback and alternative-tool advice. Every clause carries operational information; only the sprint-archived-tasks aside is slightly parenthetical, keeping it just short of a 5.

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

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

All seven optional parameters are documented in the schema, there is no output schema to explain, and the description fills the remaining gaps an agent needs: default scope, truncation handling, and how filters combine. Nothing required to call this 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 parameter documentation baseline is met structurally. The description still adds genuine meaning: it explains that from/to read as a calendar window with a six-week fallback and clarifies the interaction between from/to and result ordering, which the schema descriptions only partially 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 ('tasks'), plus the scoping axes (column, sprint, dates) and the default behavior when no filters are given. It explicitly contrasts itself with the sibling get_board_state, so an agent can select 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?

Opens with an explicit when-to-use clause, names the alternative ('Prefer get_board_state when the user wants a general overview'), and gives sample phrasings ('what is due next week?') that map user intent to this tool. It also instructs the agent to narrow filters when the 200 cap truncates results.

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=false, idempotentHint=true, destructiveHint=false, so 'Idempotent' merely repeats structured data. However, the description adds genuine side-effect context beyond annotations: moving to semantic='doing' starts cycle-time tracking and moving to semantic='done' records completion time. It stops short of disclosing reordering side effects on other tasks' positions.

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

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

Three tight sentences, front-loaded with the primary use case, then the alternative routing, then side effects. Every sentence carries information, though the 'semantic=doing/done' clause introduces a concept not present in the schema and costs some clarity.

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

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

With no output schema and no annotations covering permissions or return values, the description supplies the key behavioral facts an agent needs (idempotency, column-ID prerequisite, cycle-time/completion side effects). Missing only edge-case behavior such as what happens to the vacated position or invalid column IDs.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it partially does: it points to list_columns as the source of toColumnId and implies position controls intra-column ordering. It never explains position's indexing/range semantics (schema only gives 0..MAX_SAFE_INTEGER) and references a 'semantic' value that is not an actual parameter, which could mislead.

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 ('move a task to a specific column or change its order within a column') and immediately distinguishes the operation from start_task/complete_task. An agent can tell exactly what this tool does versus its closest siblings without opening the schema.

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

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

Gives explicit when-to-use ('move a task to a specific column') and when-to-prefer-an-alternative ('For your OWN workflow ... prefer start_task / complete_task, which need no column ID'), plus the prerequisite that a columnId must come from list_columns. Nothing 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 only say readOnlyHint=false / destructiveHint=false, so the description does the heavy lifting and does it well: it discloses the side effect of clearing a task from the review queue, that records are immutable, and that change is expressed via supersedesId rather than edits. It stops short of stating auth/permission requirements or any failure behavior, hence not a 5.

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

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

Front-loaded with the 'two uses, one table of record' frame, then cleanly enumerated as (1) and (2), so the agent can stop reading once it identifies the mode. Dense and mostly waste-free, though rhetorical asides like 'you are the messenger, not the decider' cost a little length for their guardrail value.

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

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

For a 14-parameter mutation tool with no output schema, the description covers both modes, immutability, supersession, and the downstream consumer (get_context). The one gap is the required-field discrepancy: the schema requires only 'options', while the prose states outcome is required with title, which could cause a validation surprise.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real routing value the schema cannot: it maps which parameters belong to which mode (id+decision+note for verdict relay; title+outcome+MADR fields for a standalone record). One inconsistency remains — the schema marks only 'options' as required while the prose treats title+outcome as the required record pair.

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

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

The description states a specific verb+resource ('record a decision') and then splits it into two explicitly named modes — relaying a user verdict on a task versus recording a standalone durable decision. It also names the reading counterpart (get_context), so an agent can distinguish it from siblings like update_task or complete_task without opening the schema.

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

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

Explicit when-to-use for both modes ('whenever the user makes a real choice in conversation'), an explicit when-not ('Never call this to accept your own work: you are the messenger, not the decider'), and a stated anti-pattern ('the user did not object is not a decision'). Alternative-driven routing to get_context is named for the read side.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description's 'Idempotent' and 'without deleting it' largely restate structured data. It does add a modestly useful clarification that the task remains on the board, but the safety/idempotency profile is already fully covered 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?

Three short sentences with the usage trigger front-loaded, then the outcome and idempotency note. No filler; every sentence carries information.

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

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

For a single-parameter, non-destructive tool with no output schema, the description covers the trigger, the effect, and the idempotency trait adequately. Only the absence of alternatives/prerequisites keeps it from being fully complete.

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

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

Schema description coverage is 0%, but the single parameter taskId is self-describing via its uuid format and pattern, and the description implies it identifies 'a task.' It adds no syntax, format, or sourcing detail beyond the schema's type, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource (detach a task from its current sprint) and clarifies the outcome ('without deleting it. The task remains on the board'), which distinguishes it from delete/trash siblings. It does not name a specific sibling, but the effect 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 an explicit trigger ('Use this when the user wants to detach a task from its current sprint') and implicitly excludes deletion semantics via 'without deleting it.' No explicit alternatives (e.g., add_task_to_sprint, trash_task) are named, so it stops just 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?

Well beyond the annotations, it discloses the consequence of silence (the claim expires and the task is treated as abandoned and offered to someone else) and explains why that is deliberate. This is exactly the kind of operational risk context an agent needs to keep a lease alive.

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 imperative action is front-loaded and the rationale follows in a compact three-sentence block. The middle sentence is long and clause-heavy, but every clause carries a distinct fact (cadence, consequence, design intent), so little is wasted.

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

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

With five parameters, no output schema, and annotations already covering the safety profile, the description supplies the lease lifecycle and cadence an agent must know. It stops short of describing what the call returns or how to detect an expiring lease before it lapses.

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 runId, leaseToken, note, status, and learnings are already documented; the baseline is 3. The description adds only incidental param semantics (the renewEverySeconds timing signal and that blocked/needs_input park the task), largely duplicating what the schema's status description already says.

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 line 'Say you are still working' states the action in plain terms, and the second sentence pins it to the lease-renewal mechanism ('call this ... and it renews'). It is clearly distinguishable from siblings like start_task, complete_task, and request_input.

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 an explicit cadence rule (at least every renewEverySeconds returned by start_task) and an explicit alternative use ('the place to say you are blocked or waiting on the user'). It does not name when to prefer request_input over the needs_input status, so the routing between those two overlapping mechanisms is left slightly ambiguous.

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 the safety profile (readOnlyHint=false, idempotentHint=true, non-destructive); the description goes well beyond, disclosing that the default call returns immediately rather than blocking, that repeating with identical arguments converts the call into a ~20s wait, that unanswered questions persist in the user's queue, and that each question consumes the user's attention against the same limit that blocks claiming new work. That is exactly the behavioral context annotations cannot carry.

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?

It is long, but densely informative and front-loaded — the use-only-for rule and the options preference come before the mechanics. Nearly every sentence carries distinct behavior (default flow, no-user case, wait-on-repeat, form channel, attention cost), though the middle section on repeated polling is heavy enough to slow parsing.

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

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

For an 8-parameter tool with no output schema, the description covers what each call path returns (immediate ack vs. in-call wait vs. queued answer at next start_task/get_my_work), including the no-user-present case. Nothing an agent needs to call it correctly — including the failure mode of inventing a user — is left out.

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 real semantics: why `options` matters ('a question with alternatives gets read, a yes/no gets rubber-stamped') and how `channel:'form'` changes control flow inside the call. The idempotent-recall behavior tied to `holdSeconds` is also clarified beyond the schema's terse defaults.

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 gives a specific verb+resource ('register a question only the user can answer') plus the crucial side effect ('keep your place on the task while it is open'). It clearly distinguishes itself from siblings like submit_answer (which supplies the answer) and start_task/get_my_work (where queued answers arrive), so an agent can route without opening the schema.

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

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

Explicit gate on when to use it ('ONLY for what is irreversible... or a real fork with no reasonable default') and an explicit when-not ('never for may I continue?'). It also routes to the alternatives by name — submit_answer for delivering answers, start_task/get_my_work for picking up queued answers — and explains when to reuse this call as a wait.

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 30-day recovery window is a real behavioral constraint the annotations do not carry (they only say readOnlyHint=false, destructiveHint=false). It implies restoration is bounded but doesn't state what happens to an expired id, keeping it short of a 5.

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

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

Two sentences, zero filler, and usage/trigger is front-loaded ahead of the parameter detail. Every clause earns its place.

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

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

For a single-parameter restore tool with no output schema, this covers when to use it, the source of the id, and the recovery window. Only the failure mode (id older than 30 days) is left implicit, 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 0%, so the description must carry the burden, and it does: it names the parameter's meaning and, more usefully, its source ('pass the id returned by trash_task'). It stops short of confirming uuid format, which the schema already enforces.

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 ('recover a task they deleted') and scopes it to a 30-day window. It implicitly distinguishes itself as the inverse of trash_task, so an agent can route between the two 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?

Explicitly names the trigger ('user wants to recover a task they deleted') and supplies concrete user phrasings ('undo that delete'). It also tells the agent the id comes from trash_task, closing the main invocation gap.

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

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

Annotations already declare read-only/non-destructive/non-open-world, and the description adds substantial behavior on top: case-insensitive substring matching, the exact fields searched, a ranked result list, id kind-prefixes, and a hard 50-match cap with guidance to narrow the query when truncated. That is rich, decision-relevant context 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 triggering condition is front-loaded ('Use this when...'), followed by matching semantics, scope, return shape, and the truncation limit. Despite being dense, every clause carries information an agent needs; 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?

No output schema exists, and the description compensates fully by describing the return shape ({id, title, url}), the id prefix scheme, ranking, and the 50-result cap. Combined with the annotations, nothing needed to call or interpret this tool 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% for the single 'query' param, so the baseline is 3. The description rises above it by clarifying the matching mode (case-insensitive substring) and what the query is matched against, which is useful complement to the schema's terse 'Free-text query' note.

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

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

States a concrete verb (find by keyword) and enumerates the exact resources searched — tasks, sprints, recorded decisions, memory notes — with worked examples like 'why did we choose Neon'. This clearly separates it from the enumeration-style siblings (list_tasks, list_sprints, get_board_state) even though the tool name itself is generic.

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 a clear triggering condition (user wants to find something by keyword) plus illustrative examples spanning the resource kinds. It does not name alternatives or state when a sibling like list_tasks or get_board_state would be preferable, so routing is implied rather than explicit.

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

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

Annotations only declare safety flags (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavior: the single-active-sprint invariant across every plan, the failure mode, and the fact that the error names the blocking sprint — none of which is derivable from the schema or 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, front-loaded with the use condition followed by the constraint and recovery path. Every clause carries information; no restatement of the title or schema.

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

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

For a minimal one-parameter mutation with safety annotations and no output schema, the description covers when to call it, the invariant, and the failure/recovery path. The only meaningful hole is not identifying what `id` refers to.

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

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

Schema description coverage is 0% for the single required `id` parameter. The description implies the id identifies the previously planned sprint but never states what identifier is expected (sprint UUID vs. name), so it only partially compensates for the schema gap; the UUID pattern constrains the type but not which entity.

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 (begin a previously planned sprint) and makes clear it operates on an existing sprint rather than creating one, distinguishing it from create_sprint. It does not explicitly name the sibling that creates sprints, so an agent must infer the boundary from 'previously planned'.

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 condition ('when the user is ready to begin a previously planned sprint'), the precondition that only one sprint can be active per plan, the failure behavior, and the concrete remedy (complete_sprint, then retry). Nothing about when/when-not 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 only cover the safety profile (not read-only, idempotent, non-destructive); the description adds the lease mechanism, the requirement to keep runId and leaseToken, the renewEverySeconds heartbeat obligation, the consequence of lease expiry (task offered to someone else), and the semantics of the already_claimed and attention_queue_full refusals. No contradiction with idempotentHint=true or destructiveHint=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?

Front-loads the critical timing instruction, then explains lease mechanics, then the two refusals, then the next step. Every sentence carries operational weight, with no filler or repetition.

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

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

There is no output schema, so the description correctly compensates by naming the return values (runId, leaseToken) and explaining what to do with them. For a single-parameter state-mutating tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter (id, documented as 'Task ID'). The description adds no syntax or format detail for id beyond what the schema provides, so the baseline 3 applies; it does usefully name the returned runId and leaseToken, but those are outputs, not parameters.

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 claims the task with a lease, moves it to Doing, and starts cycle-time tracking. This clearly distinguishes it from siblings like complete_task, report_progress, and move_task, which an agent can route between 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 to call it ('the moment you begin executing a task — BEFORE doing the actual work') and names the follow-up alternatives (report_progress while working, complete_task when done). It also pre-declares the two normal refusals so the agent does not misinterpret them as errors.

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 idempotency, non-read-only, and closed-world; the description adds far more: the runId/leaseToken return values, that the same attempt and context are resumed, and the non-obvious edge behavior that an answer submitted elsewhere is returned instead of an error. It also warns against fabricating an answer, which is the key correctness failure mode.

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 action is front-loaded, and the do-not-call condition and return semantics follow in a sensible order. The messenger/'an answer you invented is worse than no answer' line is slightly rhetorical for a tool description, but it earns its place by encoding the fidelity requirement.

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 compensates by stating what is returned (runId and leaseToken) and how the run continues, plus the failure and alternate-client cases. Nothing an agent needs to call this 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 description coverage is 100%, so questionId, answer, and value are already documented, including 'in their words' and 'when they picked one' for value. The description reinforces the verbatim-fidelity requirement for answer but adds no format, length, or selector detail beyond the schema, so the baseline 3 applies.

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

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

The description names a concrete verb and resource — deliver the user's answer back to a pending request_input question and resume the paused run — and explicitly ties itself to the sibling tool request_input. An agent can distinguish it from every other sibling (which are task/sprint/project mutations) without opening the schema.

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

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

It gives an explicit trigger ('call it the moment they answer'), an explicit exclusion ('if they declined to answer, or nobody was there, do not call this: leave the question in their queue'), and covers the alternate-path case where the user answered in another client. When-to-use, when-not-to-use, and the alternative are all stated.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it discloses soft-delete semantics, the 30-day restore window, the eventual physical deletion by a scheduled job, and the restore_task escape hatch. That is exactly the extra context an agent needs for a destructive operation.

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

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

Three short sentences, front-loaded with the trigger, then behavior, then the safety rule. Every sentence earns its place; nothing is redundant with the schema or annotations.

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

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

For a one-parameter destructive tool with no output schema, the description covers the trigger, the reversible-vs-permanent lifecycle, the recovery path, and the disambiguation requirement. Nothing an agent needs to call it safely 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 single 'id' parameter has 0% schema description coverage, so the description must carry the burden. It implies the id must resolve to exactly one task via the disambiguation rule, but never states the identifier format or that a UUID is required — the schema's pattern is left to speak for itself.

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 ('Moves the task to the trash') and explicitly contrasts with the sibling restore_task. An agent can distinguish it from archive_done_tasks, remove_task_from_sprint, and update_task 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?

Names the triggering condition ('when the user asks to remove or delete a task'), the recovery alternative (restore_task), and an explicit exclusion rule ('If multiple tasks match... ask the user to pick one — do not guess'). This is full when/when-not/alternative 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?

Goes well beyond the annotations: it defines the partial-update contract ("Only fields you pass are changed"), the side effects of archival on pickers and task associations, how to reverse it (archived: false), and where old values go (the board's journal). The "Idempotent" claim is consistent with idempotentHint=true and destructiveHint=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?

Three dense sentences, front-loaded with the use case, then the archive semantics, then the update/journal contract. Every clause carries information; no filler or restatement of the title.

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 mutation semantics, partial updates, and reversibility for a tool with no output schema and no parameter-level schema docs. It does not state permission/auth requirements or what the call returns, which are the remaining gaps for a write operation.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the semantics of name, color, url, and especially the boolean archived (hide from pickers, tasks keep association, false restores) and the partial-update behavior. It omits any note on the required id or the nullability of url, hence not a 5.

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 (update) plus the exact mutable fields of the resource: rename, color, website url, archive/unarchive. An agent can distinguish it from create_project, list_projects, and update_task 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?

"Use this to rename a project, change its color or website url, or archive/unarchive it" gives clear triggering conditions for each mode of use. It does not name a sibling alternative or state when NOT to use it (e.g., use create_project for new projects), so it stops short of full routing 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?

Goes well beyond the annotations: explains patch semantics (omitted fields unchanged), that replaced values land in the journal and edits are reversible, that the operation is idempotent, and — most valuably — that a patch attempting to clear requiresReview is refused wholesale so no other field is written. That atomic-failure behavior is not inferable from the schema or 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-loads the trigger, then layers patch semantics, reversibility, and the requiresReview exception in descending order of importance. The long requiresReview sentence is dense but carries a constraint an agent would otherwise get wrong; 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 12-parameter mutation with no output schema, the description covers the two things most likely to cause incorrect calls: partial-patch expectations and the refused-write case. It leaves some gaps — no mention of what a successful response looks like, or how a bad project name or unknown id is reported — but the schema absorbs most field-level detail.

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 12 parameters and only 50% schema description coverage, the description compensates for the highest-risk ones: it establishes the partial-update contract so the agent knows an unset field means "leave alone," and it spends its detail on requiresReview's asymmetric on/off rule. The remaining parameters (dueAt, startAt, assignee, blockedBy, verification) get no description-level meaning, though several carry strong inline 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?

Opens with a specific trigger and verb set ("rename, re-prioritize, re-estimate, or otherwise edit an existing task"), which pins this as an in-place edit rather than a create (create_task) or a status/column move (move_task). The field list makes the resource boundary concrete.

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 when-to-use condition tied to user intent, and names two adjacent tools in their proper roles (get_task_history for reverting, complete_task for releasing flagged work). It lacks a clear "don't use this for X, use move_task/trash_task instead" exclusion, which is the remaining gap for a full 5.

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