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

No annotations are provided, so the description carries the full burden of disclosure. It only states the core append action and does not mention side effects on the plan file, whether the iteration/version must exist, or how the agent and done fields affect touched lines.

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

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

The description is a single, front-loaded sentence with no filler or restatement. It is concise, though slightly too sparse to fully carry the tool's context.

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 five parameters, no annotations, no output schema, and several sibling tools, a one-line description leaves important gaps: what file is modified, how version identifies the iteration, what the task entry looks like, and when to prefer the plural add_tasks.

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

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

Schema description coverage is only 40%, and the description does not compensate. It does not explain the required version and text parameters or the done flag; only agent and plan_path have schema documentation. 'Checkbox task' hints at a done state but is not explicit about parameter behavior.

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

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

The description names a specific verb ('Append'), a specific resource ('checkbox task'), and a location ('to an iteration'), so an agent can mostly discern what add_task does. However, it does not explicitly distinguish add_task from the plural sibling add_tasks, so it stops short of full sibling differentiation.

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

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

The description gives no when-to-use guidance, prerequisites, or exclusions. With siblings like add_tasks and add_to_backlog present, there is no statement about when to choose add_task instead, leaving selection to inference.

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

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

With no annotations, the description carries the full behavioral burden. It adds useful context by saying this is a single write and that done/agent apply to every item, but it does not disclose side effects, permissions, return behavior, or how 'checkbox tasks' are formatted. Some behavioral transparency is present, but gaps remain.

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, each earning its place: the core action, the selection guidance, and the shared-parameter behavior. It is front-loaded and free of filler.

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

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

The description covers purpose and usage well and the schema covers most parameters, but the required 'version' field is entirely undocumented in both schema and description. With no output schema and no annotations, this is a noticeable gap for an agent that must provide a valid version value.

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 80%, so the schema already documents most parameters. The description reinforces that done/agent are shared across all tasks, but this largely restates what the schema says. The required 'version' parameter still has no description and is not explained in the tool description.

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

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

The description clearly identifies the action ('Append'), the resource ('checkbox tasks'), and the batching mode ('in one write'). It also differentiates from the sibling add_task by explicitly preferring this tool over repeated add_task calls.

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

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

The description explicitly states when to use this tool: for appending several tasks at once, and names the alternative ('repeated add_task') that it is preferred over. This gives an agent clear selection guidance without needing to open the schema.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does state that the operation is an append and emphasizes a single write, which communicates the basic side effect. However, it does not disclose what file or data structure is modified, whether anything can be overwritten, or how checkbox and plan_path affect behavior.

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

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

The description is a single efficient sentence with no filler. It front-loads the action and destination, then succinctly captures the one-write behavior.

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

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

The tool has five parameters, no required parameters declared, no annotations, and no output schema, so the description must compensate. It leaves important invocation details missing: what checkbox means, whether text and texts are mutually exclusive, and how plan_path is resolved beyond the schema text.

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 80%, so the schema already documents most parameters. The description adds the text/texts single-vs-multiple distinction and the 'one write' nuance, but it does not clarify checkbox semantics or whether text and texts can both be provided.

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

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

The description names a specific verb ('Append') and a distinct resource ('Future (Backlog)'), so the agent understands what is being modified. It does not explicitly contrast itself with siblings like add_task or add_tasks, though referring to the Backlog rather than tasks provides some differentiation.

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

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

The description gives no guidance on when to choose this tool over alternatives, and it does not mention exclusions, prerequisites, or alternative sibling tools. The only implicit signal is that it targets the Backlog resource.

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

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

With no annotations at all, the description carries the full burden of behavioral disclosure. 'Append' implies a mutating operation, but it does not disclose side effects, whether it edits PLAN.md in place, how 'top level' insertion works, idempotency, error behavior, or any permissions/requirements. This is insufficient for a write 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?

The description is a single, well-paced sentence with no wasted words and the key action front-loaded. It loses a point only because brevity crosses into under-specification, leaving important referents vague.

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

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

Given no annotations, no output schema, 50% parameter coverage, and a likely mutating effect on a plan document, the description is far too thin. It fails to explain the target ('top level' of what?), the default plan_path behavior (though the schema hints at it), or what happens on invocation. An agent would need significant external inference to call this confidently.

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 50%: plan_path already has a clear description, but text only has a type. The phrase 'freeform markdown' adds meaningful semantics to the text parameter, indicating unconstrained Markdown content. However, the description adds nothing about plan_path beyond the schema, so it only partially compensates for the schema 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?

The description identifies the action (append) and the content (freeform markdown), but 'top level' is ambiguous—it does not name the target document (e.g., PLAN.md) or specify whether 'top level' refers to document structure, sections, or something else. This makes it hard to distinguish from related append-like operations among the many plan-management siblings.

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

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

No guidance is provided about when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or scenarios that favor append_prose over e.g. add_task, update_task, or add_to_backlog. Usage context must be inferred entirely from the name and sibling list.

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?

No annotations are provided, so the description carries full responsibility for disclosing safety and side effects. It implies read-only analysis via 'lint' but never states that nothing is modified, what output is produced, or whether failures (issues found) affect the exit code. The listed check categories give some context but not enough for an agent to predict the tool's behavior.

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 very short and front-loaded, naming the tool type as 'Structure lint' before listing what it checks. It avoids redundancy with the schema and contains no filler. However, it is a fragment rather than a complete sentence, which slightly reduces 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?

For a tool with no output schema and no annotations, the description should explain what the result looks like and confirm the operation is non-destructive. It lists the lint categories but omits how the tool reports issues and what an agent should do with the result. The missing behavioral details make it incomplete for safe autonomous use.

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

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

The schema already documents plan_path fully with default behavior (walk up to nearest PLAN.md) and absolute/relative usage, so schema coverage is 100%. The description adds no additional meaning about the parameter; baseline 3 is appropriate.

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

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

The description names the operation as a 'structure lint' and enumerates specific checks (duplicates, multiple current, complete-with-open-tasks), making it clear this is a validation tool for the plan. However, 'lint' is not a plain verb and the resource is implied rather than stated. It is distinguishable from sibling tools like show_plan or create_plan because it checks rather than displays or edits.

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

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

The description provides no explicit guidance on when to use this tool instead of siblings. There is no mention of a workflow, such as validating a plan before starting an iteration, or any alternative tool to use when simply viewing the plan. Usage must be inferred entirely from the 'lint' label.

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

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

With no annotations, the description carries the transparency burden. It clearly signals a state-changing operation, exposes the force requirement for open tasks, and notes that an optional stamp modifies the title. However, it does not disclose side effects of force=true, reversibility, or any return behavior.

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, front-loaded sentences with no filler or redundancy. The core action comes first, followed by the key precondition and optional behavior.

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

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

The description covers the essential operation, the force condition, and the stamp behavior. However, it omits what version refers to, what happens to open tasks when force=true, and what the tool returns. Given no annotations and no output schema, a bit more context would be needed for fully confident invocation.

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

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

The description adds real meaning for force ('true if open tasks remain') and stamp ('appended to title'), but the required version parameter is left completely unexplained. With only 25% schema description coverage, this is a significant gap that the description does not fill.

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

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

The description states a concrete action and target state: 'Mark iteration COMPLETE.' This is clearly distinct from sibling tools like start_iteration and complete_task, though it does not explicitly contrast with them.

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

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

The description implies when to use the tool by naming the action, and it provides a useful precondition: force=true is required if open tasks remain. However, it does not explicitly discuss alternatives or when not to use this tool.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It only says 'in one write', hinting at batched mutation, but does not mention side effects, version requirements, refusal behavior with expect, or failure semantics. This is a significant gap for a state-changing tool.

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

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

Three short sentences, each earning its place: the first defines the operation, the second covers multi-task addressing, and the third covers single-task addressing. It is front-loaded with the core purpose and contains 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?

The description covers the main addressing modes and references get_iteration, which is helpful. However, it omits what the required 'version' parameter should be, does not describe the expected guard/refusal behavior, and lacks any note about side effects. The schema fills some gaps, but the overall description is only minimally complete for a mutation tool with 8 parameters.

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 high (88%), so the baseline is 3. The description adds value by summarizing the addressing rules: indexes are preferred after get_iteration, and tasks also work; single tasks accept index or task. This helps agents choose between the many addressing parameters beyond what the schema lists individually.

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

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

The description states a clear verb and resource: 'Tick one or many tasks in one write.' This distinguishes complete_task from add/reopen/update/defer operations. However, it does not explicitly name sibling alternatives to differentiate against, so it falls just short of a 5.

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

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

The description gives concrete usage context: for multiple tasks, 'pass indexes (preferred after get_iteration) or tasks', and for exactly one, 'index or task still work'. This is clear guidance on addressing modes, though it does not explicitly state when not to use the tool or name alternative tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely says 'Create' and omits whether the tool writes to a file, modifies a plan, requires an existing plan, or is reversible.

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 extremely short, but this is under-specification rather than effective conciseness. The single template string does not provide enough information to be useful.

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 8 parameters, no output schema, no annotations, and a large sibling set, the description is far from complete. An agent would be guessing about required behavior, parameter roles, and expected results.

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

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

Schema description coverage is only 25%, so the description must compensate for undocumented parameters. It adds a weak formatting hint for version and title, but says nothing about goal, major, status, description, or how the parameters relate to the created iteration.

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

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

The description uses a verb and a template-like resource ('Create ### vX.Y.Z — Title iteration'), but it never explains what an iteration is, what side effect 'Create' produces, or how this differs from sibling tools like create_plan and create_major. The placeholder format is suggestive rather than clarifying.

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

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

There is no guidance on when to use this tool versus alternatives. With 21 siblings including create_plan, create_major, start_iteration, and set_iteration_goal, an agent has no basis for selecting this tool.

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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It only says "Create," implying mutation, but does not explain whether this appends to PLAN.md, overwrites existing content, requires special permissions, or what the operation's side effects are. This is a significant gap for a write operation with no annotation coverage.

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 short, but it is under-specified rather than efficiently complete. The heading template is useful and front-loaded, but the single sentence omits essential context, making it closer to a stub than a well-structured definition.

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

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

With four parameters, no annotations, no output schema, and 25% schema coverage, the description does not provide enough context for correct invocation. Missing details include how plan_path is used, what description should contain, what the resulting plan change looks like, and any side effects or return behavior. The entry is only minimally viable.

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

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

Schema description coverage is only 25%, so the description must compensate. It partially clarifies that version and title form the heading, but it does not explain the description parameter or the plan_path behavior, and it leaves version format ambiguous beyond the literal "vX.Y" pattern. The added value is minimal relative to the parameter count.

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: it creates a major section with heading format "## vX.Y — Title". However, "major section" is never defined in relation to PLAN.md or any other artifact, and the description does not distinguish it from siblings like create_plan or create_iteration. The purpose is recognizable but ambiguous.

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

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

There is no guidance on when to use this tool versus create_plan, create_iteration, or add_task. The description gives no context about which workflow step it belongs to or what qualifies as a major section. An agent cannot confidently route between this and alternatives.

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

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

With no annotations, the description must carry full behavioral disclosure. It does reveal safety behavior around overwrites and the default path, but it omits the skeleton's contents and side effects. More critically, the description's default path './PLAN.md in cwd' conflicts with the schema's plan_path description, which says the default is to walk up from cwd to the nearest PLAN.md, making actual behavior ambiguous.

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-load the purpose, then the path and overwrite constraint. Each sentence adds a distinct piece of information with no filler or unnecessary details.

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

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

For a 6-parameter creation tool with no annotations and no output schema, the description is too sparse: it omits what the skeleton contains, how title, goal, philosophy, and seed_major affect the output, and what happens on failure or success. The path contradiction also leaves the agent without a reliable behavioral model.

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

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

Schema description coverage is only 50%, leaving title, goal, and philosophy undocumented, and the description does not explain these parameters. It repeats force's overwrite behavior already present in the schema and gives a default path that contradicts plan_path's schema description, failing to 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?

The description uses the verb 'bootstrap' with a specific resource, 'a new PLAN.md', and states the condition 'when none exists' and the default location. This clearly distinguishes it from sibling tools like create_major or create_iteration, which operate on plan components rather than the root file.

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

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

The phrase 'when none exists' gives an explicit precondition, and 'Refuses overwrite unless force=true' signals when the force parameter is required. It does not name alternative tools such as check_plan or update tools, so it provides clear context but no explicit exclusions or when-not-to-use guidance.

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

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

No annotations are present, so the description must carry behavioral weight. It discloses batching ('in one write') and propagation of shared reason/agent, but it does not mention version-guard behavior, the effect on the current iteration, or failure semantics.

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 concise sentences front-load the purpose ('Move one or many tasks to the backlog in one write') and then give the key usage constraints. 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 9-parameter mutation tool with no annotations, the core behavior, batch addressing, and shared-field effects are covered. The undecorated required parameter (version) and optional guard (expect) are left to the schema, which prevents full completeness but is acceptable because the schema documents them.

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 89%, setting a baseline of 3. The description adds cross-parameter guidance: 'For several, pass indexes or tasks' and 'Shared reason/agent apply to every item,' which clarifies how the array and single modes relate. It does not add meaning to the undecorated version parameter.

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

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

The description names a specific action ('Move') and resource ('the backlog') and scopes it to one or many tasks. It does not explicitly contrast with sibling tools like add_to_backlog, but the move semantics make the intent reasonably distinguishable.

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

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

It gives clear invocation context: for several tasks, pass indexes or tasks, and shared reason/agent apply to every item. It lacks an explicit when-not-to-use or alternative statement, but the core use case 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?

There are no annotations, so the description carries the full burden. It reveals only a substring-match mechanism and possibly a JSON output format; it does not disclose whether the operation is read-only, which fields are matched, case sensitivity, or what the returned data contains.

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

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

The entire description is one short, front-loaded sentence with no filler. It is concise, but the ambiguous '(JSON)' and lack of any structured elaboration make it slightly under-specified rather than optimally structured.

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

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

For a simple two-parameter read-style tool, the description gives the basic action and a JSON hint, and the schema documents plan_path. However, with no output schema and no annotations, the description should say more about what a caller receives and how the substring match is applied.

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 50%; 'text' has no schema description, and 'plan_path' does. The description clarifies that 'text' is a substring to match, which adds some meaning, but it does not specify which task fields are searched or any matching rules, so it only partially compensates 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?

The description uses a specific verb ('Locate'), a clear resource ('tasks'), and a defined search method ('substring match'), which distinguishes it from sibling task-mutation tools. The parenthetical '(JSON)' is slightly ambiguous—it likely indicates output format but is not explicit—so this is not a 5.

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

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

No guidance is given about when to use this tool instead of alternatives. The description does not name sibling tools, state that this is the only substring-search option, or specify when it should not be used.

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

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

With no annotations and no output schema, the description carries the full burden of behavioral disclosure. It only states that the result is JSON; it does not mention side effects, failure modes, path resolution behavior, or whether it only reads data. This is minimal but not entirely absent.

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

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

The description is extremely concise and front-loads the key concept 'backlog section items'. It contains no filler words, though it is arguably too terse to be fully self-sufficient.

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

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

For a tool with no annotations, no output schema, and only a one-line description, the definition is incomplete. It does not explain what the returned items look like, how the optional plan_path behaves, or what distinguishes this from similar tools. The agent is left with too much uncertainty.

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

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

Schema description coverage is 100%, and the only parameter, plan_path, is already documented in the schema. The description adds no parameter information, but the baseline of 3 applies because the schema already does the heavy lifting.

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

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

The description names a specific resource ('backlog section items') and its return format ('JSON'), which is enough to distinguish it from iteration- and plan-focused sibling tools. It lacks an explicit verb, but the tool name 'get_backlog' supplies the action, so the intended operation is clear.

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

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

There is no guidance on when to use this tool versus alternatives such as get_iteration, get_current_iteration, or add_to_backlog. No conditions, exclusions, or selection criteria are provided, so the agent must infer usage solely from the name.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals that the tool returns JSON and is efficient because it avoids reading all of PLAN.md, which is useful. But it does not mention error conditions, what happens if no PLAN.md exists, or any side-effect profile, though the read-only nature is strongly implied.

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

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

The description is two short clauses with no wasted words. It front-loads the core output and then provides the usage rationale, exactly the kind of compact, efficient definition that helps an agent.

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 tool with one optional parameter and no output schema, the description is nearly complete: it states the return type (JSON), the target (current iteration), and when to prefer it. It lacks explicit error behavior and sibling differentiation, but neither is likely to block correct invocation in the normal case.

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

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

The schema already documents plan_path with 100% coverage, including its optionality and default behavior. The description does not add parameter-specific details, so it neither helps nor hurts; the baseline of 3 applies.

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

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

The description clearly states what the tool does: returns JSON for the current iteration, with the parenthetical clarifying 'what to work on now.' It is specific about the verb and resource, and the mention of being the 'preferred agent entry' offers some distinction, but it does not explicitly differentiate from sibling tools like get_iteration or show_current_iteration.

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

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

The description gives clear context for when to use it: it is the 'preferred agent entry' and avoids reading all of PLAN.md, implying the main alternative is manually reading the file. However, it does not explicitly state when to prefer other tools or provide exclusions, so it falls 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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It only says the result is JSON with goal, tasks, and progress; it does not mention whether the operation is safely read-only, what happens for missing/invalid versions, or how plan_path resolution affects the result.

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

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

The description is a single sentence with no filler, and the most important qualifier ('by version') is placed early. It is concise and front-loaded, though it could afford a bit more behavioral detail.

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 get tool with two flat parameters, the description is close to adequate: it names the resource and the return contents. However, it lacks explicit usage context, sibling differentiation, and any statement about behavior on missing data or plan_path handling, so an agent may need to infer edge-case behavior.

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

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

The schema documents plan_path well but gives no description for version, and the description's 'by version' provides minimal semantic meaning for the required parameter. That partially compensates for the 50% schema description coverage, but details like version matching or format are left unspecified.

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

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

The description states a clear operation (get), a specific resource (one iteration), and a key qualifier (by version), and it lists the returned contents (goal, tasks, progress). It does not explicitly name or contrast sibling tools, but 'by version' helps distinguish it from get_current_iteration and list_iterations.

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

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

There is no explicit guidance about when to use this tool versus alternatives like get_current_iteration, list_iterations, or show_current_iteration. The phrase 'by version' implies a selection condition, but it does not tell the agent when this tool is the right choice or when it is not.

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?

No annotations are provided, so the description carries the behavioral burden. 'List' signals a read-only operation and the filter options are explicit, but the description does not mention return format, ordering, or behavior when no PLAN.md is found. Acceptable but minimal.

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

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

The description is a single front-loaded sentence with no filler. It packs the action, resource, and filter options efficiently, making it easy to parse.

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

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

For a simple read-only list tool with a schema that documents the optional plan_path, the description is nearly complete. The main gap is the lack of guidance on choosing this versus sibling iteration tools and any caveat about PLAN.md discovery failures.

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 50%: plan_path is documented in the schema, and filter has an enum. The description repeats the filter values but adds little beyond the schema. It does not clarify plan_path behavior in prose, but the schema already handles that adequately.

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

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

The description clearly states a specific verb ('List') and resource ('iterations'), with the filter scope 'open | complete | all'. It is distinct enough from sibling 'get' tools, though it does not explicitly call out which sibling to use instead.

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

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

The description implies this is for listing iterations, but it gives no guidance about when to choose this over siblings like get_iteration or get_current_iteration. No exclusions or alternative tool routing is provided.

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

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

With no annotations, the description carries the full burden. It reveals an important execution guarantee: 'Resolve-all then drop (indexes do not shift),' along with the claim that multiple deletions happen in 'one write.' This is meaningful behavioral context beyond the schema, though it does not address irreversibility or failure modes.

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

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

Three short sentences with no wasted words. It front-loads the primary action, then gives concise addressing guidance, then a key behavioral guarantee. Every sentence earns its place.

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

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

For a 7-parameter deletion tool with no output schema and no annotations, the description covers core deletion semantics and batch resolution behavior, but it omits the role of the required 'version' parameter and any expected result or error context. The schema compensates partially, but overall completeness is only minimally sufficient.

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

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

Schema description coverage is 86%, so the baseline is 3. The description's 'pass indexes or tasks' largely restates the schema's addressing-mode descriptions. It adds no further detail on the required 'version' parameter or the optional 'expect' guard.

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: 'Delete one or many tasks in one write.' It also clarifies scope and batch capability, clearly distinguishing this from siblings like complete_task, reopen_task, and update_task which are non-destructive.

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

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

No explicit when-to-use or alternatives are named. The verb 'Delete' makes the core context obvious, and 'For several, pass indexes or tasks' guides addressing mode, but the description does not say when to prefer this tool over siblings or when to avoid it.

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

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

No annotations are provided, so the description carries full behavioral burden. It only says 'one write', implying batch atomicity, but does not disclose concurrency requirements, side effects on iteration state, whether the operation is reversible, or failure behavior. For a mutating tool, this is a significant gap.

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

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

Two short sentences with no filler. The core action is front-loaded, and the addressing guidance is compact and immediately useful.

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?

Tool is a mutation with no annotations and no output schema, yet the description omits important context like required version usage, the expect guard, plan_path behavior, and what happens on refusal or mismatch. Given the 8-parameter complexity, the description is too thin to be complete.

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

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

Schema coverage is high at 88%, and the schema already documents each parameter. The description adds value by clarifying the singular/plural addressing convention: exactly one can use index or task, while several use indexes or tasks. This integration is not fully stated in the schema.

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

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

The description states the action precisely: 'Untick one or many tasks in one write.' This clearly identifies the resource (tasks) and the operation (unticking), and distinguishes it from siblings like complete_task without needing to open 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 concrete guidance on addressing modes: for several tasks use 'indexes or tasks', for exactly one use 'index or task'. This helps the agent choose among the many parameters. It does not explicitly name alternatives like complete_task, but the semantic contrast is strong enough that the usage context 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?

With no annotations, the description must disclose behavioral traits itself. It reveals that the operation replaces an existing goal (destructive), but it says nothing about versioning semantics, error behavior, side effects on the iteration, or permissions. This is a significant gap for a mutation tool.

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

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

The one-sentence description is efficiently written with no wasted words, but it is under-specified rather than optimally concise. It lacks any structure to convey usage or parameter context, making it less useful than a slightly longer, better-organized description.

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 two required parameters and no output schema, the description is incomplete. It omits how the iteration is selected, what version means, how plan_path resolves, and what happens on success or failure. An agent would need to infer or discover critical details.

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

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

Only plan_path has a schema description (33% coverage), and the tool description does not explain goal or version. 'Goal' is somewhat inferable from the tool name, but 'version' is ambiguous (likely optimistic concurrency) and the relationship between version, plan_path, and target iteration is unexplained. The description adds little beyond the schema.

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

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

The description uses a specific verb ('Set/replace') and identifies the resource ('Goal on an iteration'), so the core action is clear. It also distinguishes itself from sibling tools like create_iteration or update_task by focusing on the goal field, but it does not specify which iteration is targeted or how it is identified, preventing a top score.

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

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

No guidance is provided on when to use this tool versus alternatives such as create_iteration or update_task. The description does not mention prerequisites, whether it should be called after creating an iteration, or when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The word 'view' and 'ASCII view' imply a read-only operation, which is helpful. But it does not clarify whether the tool emits the result directly, how 'resolved' works, or what happens when no current iteration exists.

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

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

The description is a single, tightly written sentence with no filler. The output type and intended audience are front-loaded, and every part 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 tool with one optional parameter, the description is workable, but it omits details about exact return content, resolution behavior, and edge cases such as a missing current iteration or invalid plan_path. Since there is no output schema, the description alone must carry more of that burden.

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 one parameter plan_path is already fully documented in the schema. The description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate.

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

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

The description identifies a specific resource ('the resolved current iteration') and a specific output form ('ASCII view'), with a clear audience ('humans/logs'). This implies a distinct purpose from the sibling get_current_iteration, though it never explicitly names or contrasts that alternative.

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

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

The parenthetical '(humans/logs)' gives an implicit usage signal: use this for human-readable display or log output rather than programmatic retrieval. However, it does not explicitly state when not to use it or name an alternative such as get_current_iteration, leaving some selection work 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the output content (counts + current iteration) but does not disclose that this is a read-only operation, what happens if no PLAN.md is found, or what exactly the counts refer to. For a tool with zero annotation coverage, this is a notable gap.

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

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

Two sentences with zero filler: the first states what the tool is, the second gives routing guidance. The most important information (compact index, prefer alternatives) is front-loaded, and every sentence earns its place.

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

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

For a simple tool with one optional parameter and 100% schema coverage, the description is mostly complete. However, with no annotations and no output schema, it should disclose the read-only safety profile and what 'counts' encompasses to be fully self-sufficient. These gaps keep it at adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema fully documents the single optional plan_path parameter, warranting the baseline of 3. The description adds no parameter-specific detail, but none is needed given the schema covers everything about the parameter.

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

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

"Compact index: counts + current iteration" states the tool's function with a specific noun phrase that describes what it returns, and it explicitly contrasts itself with get_current_iteration / get_iteration, distinguishing it from siblings. It lacks a true verb but is specific enough for an agent to understand the resource and scope.

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

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

The description explicitly tells agents to prefer get_current_iteration / get_iteration over this tool, and references full PLAN.md as another alternative. It clearly communicates when NOT to use it, though it doesn't fully spell out the positive condition ('use this when you need a quick overview/counts' is implied rather than stated).

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

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

With no annotations, the description carries the behavioral burden. It does disclose a meaningful side effect ('clears other current markers'), but it does not state whether the operation is reversible, idempotent, or what happens on invalid input.

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

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

The description is a single compact sentence that front-loads the core action and immediately states the key side effect. There is 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?

Given no annotations and no output schema, the description leaves important gaps: it does not explain the required 'version' parameter, nor does it give enough context for an agent to safely invoke the tool without additional assumptions. The side effect is clear, but the operational context is incomplete.

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

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

The required 'version' parameter has no schema description and the tool description does not explain what 'version' refers to or what values are valid. Schema coverage is only 50%, and the description adds no parameter-level meaning; only plan_path is documented in the schema.

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

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

Description uses a specific verb ('Mark') and resource ('iteration'), clearly stating the resulting state ('ACTIVE / current') and the side effect ('clears other current markers'). This clearly distinguishes it from sibling tools like get_current_iteration and close_iteration.

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

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

The intended usage is implied by the name and semantics: starting or switching to an iteration. However, there is no explicit guidance on when to use this tool versus alternatives, no mention of prerequisites, and no exclusions.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose one meaningful behavior: 'preserving done state', which clarifies that rewriting text does not alter completion status. However, it omits other behavioral traits such as the agent-tag side effect, the expect guard semantics, and the default plan_path lookup, so transparency is partial.

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 very compact and front-loads the core purpose before presenting usage patterns. Both sentences earn their place with no filler. The shorthand notation is terse but still readable; a little more explicitness about the omitted modes would be the only improvement.

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

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

The tool has 10 parameters, multiple addressing modes, a required 'version' parameter, and no output schema or annotations. The description covers only the singular and changes modes, omitting the valid tasks and indexes arrays, and does not explain the required 'version' parameter, which has no schema description either. This leaves an agent without enough context to safely invoke every supported usage.

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 90%, so the baseline is 3, but the description adds relational parameter semantics: it groups 'text + index/task' for a single task and 'changes[{text, index|task, expect?}]' for several tasks, making mode exclusivity explicit. This goes beyond the flat schema properties and helps an agent understand which parameters combine. It omits the tasks and indexes arrays, though those are already described in the schema.

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

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

The description clearly states the verb and resource: 'Rewrite task text', and adds the important qualifier 'preserving done state', which distinguishes it from state-changing siblings like complete_task and reopen_task. It does not fully enumerate all addressing modes (tasks and indexes arrays are omitted), but the core purpose 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?

There is no explicit guidance on when to prefer update_task over sibling tools such as add_task, append_prose, or complete_task. The description gives some within-tool usage patterns for single vs. several tasks, but it does not provide decision rules or exclusions relative to alternatives.

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