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

Annotations are absent, so the description carries the full burden, and it delivers richly: targets are never built, never listed by list_ready, map to a GitHub issue whose sub-issues are tasks, forbid build fields, and their deps 'sort its work below rows that are clear' while priority 'multiplies the rank of everything it holds.' This goes well beyond a bare mutation disclosure.

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

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

Front-loaded with the definition, then constraints, then parameter behavior; every sentence earns its place and there is no boilerplate. It is long, but the conceptual complexity (target vs. task, altitude, derived progress) justifies the length rather than padding it.

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

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

For a 10-parameter, semantically unusual tool with no annotations, the description covers the concept, exclusions, required fields, the 'why' criterion, and dependency ranking. It omits edge behavior (deps cycles, what happens if a build field is passed anyway) and doesn't route to roadmap/list_planning siblings, but with a 100%-coverage schema and an output schema present, these are minor gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some nuance — deps 'rank every task underneath' and the WHY-test for brief ('If you cannot write the why, it is not a target yet') — but much parameter meaning (priority multiplier, tags replace behavior, project default, brief definition) already lives in the schema, so the net addition beyond structured fields is thin.

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

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

Opens with a specific verb+resource — 'Create a roadmap TARGET' — and immediately distinguishes it from siblings: 'A target is never offered by list_ready and is NEVER BUILT,' with progress 'derived from the tasks that name it (add_task/edit_task `target`).' An agent can tell add_target apart from add_task and list_ready 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 when-not and route: 'If you cannot write the why, it is not a target yet; file it as a task, or leave it unfiled,' and references the sibling add_task by name. It also states hard exclusions (cannot carry build fields, cannot serve another target). However, it never states a positive 'use this when...' instruction or compares against roadmap/list_planning siblings, so positive routing is left mostly 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 behavioral disclosure burden. It does add a meaningful behavior: 'Fails if the id exists,' which warns against duplicate creation. However, it does not mention other side effects, permissions, downstream consequences, or the non-idempotent nature beyond that one 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?

Three short sentences with no filler. The core action is front-loaded, and each subsequent sentence provides distinct useful information about input format and duplicate-id failure.

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 schema already documents all 17 parameters and an output schema exists, so return details are not required. Still, this is a complex mutation tool with many siblings and no annotations; the description omits any selection guidance, prerequisite context, or broader side-effect information, making it minimally 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 baseline is 3. The description adds value by explicitly stating that deps/scope accept an array or a comma string, which clarifies the anyOf schema type, and by noting the id uniqueness failure condition.

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

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

The description opens with 'Create a task,' a clear verb+resource statement that distinguishes this tool from edit, amend, close, delete, and start siblings. It does not explicitly compare itself to add_target or other creation-adjacent tools, so it falls short of full 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?

Usage is implied through 'Create a task' and the tool name, but there is no explicit guidance about when to choose add_task over edit_task, amend_task, or add_target. No exclusions or alternative-selection conditions are 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 behavioral burden, and it does this well by disclosing that done tasks are refused and that scope changes are strictly additive. It doesn't cover every edge case like error responses or auth requirements, but the most important behavioral guardrail is clearly stated.

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

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

Two compact sentences: the first states the primary function, and the second states a hard constraint plus the alternative tool. Every clause earns its place, and no information is buried or repeated.

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

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

The description covers the operation, the failure condition, the add-only restriction, and the relevant sibling alternative. Since an output schema exists and all parameters are documented, nothing critical is missing for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and schema descriptions already explain each parameter, including that scope is added, project is opaque, and branch use is backend-decided. The description reinforces the add-only scope semantics, but it adds little beyond what the schema already provides.

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

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

The description names the specific action ('Widen an open task's scope and/or set its brief') and the resource ('task'), and immediately distinguishes itself from edit_task. The add-only constraint further clarifies the tool's precise role, so an agent can select it confidently.

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 (widen scope, set brief), explicit when-not-to-use guidance (refuses done tasks), and names the alternative edit_task for narrowing/removing fields/setting labels. This leaves little inference to the agent.

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 behavioral disclosure burden. It explicitly reveals the external side effect of posting a comment on a GitHub issue and the precondition that an issue must exist. This is useful because the operation is mutating and depends on external state, even though it does not detail failure modes or idempotency.

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

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

Two dense sentences with no filler. The action and mechanism are front-loaded, and the crucial prerequisite is stated in the second sentence. 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 tool with an output schema and six parameters, the description provides the essential operational context: what it does, how it does it, why it is useful, and the prerequisite to satisfy before calling it. An agent has enough information to select it and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds only indirect context by framing the operation as appending a comment-based trail entry, which hints at the role of note but does not materially improve on the schema's own parameter 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 uses a specific verb and resource: 'Append one entry to a task's trail by posting a comment on its GitHub issue.' This clearly differentiates it from the sibling get_trail, which reads the trail, and from edit_task/amend_task, which modify task fields rather than append trail entries.

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

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

It states a clear prerequisite and directs the user to sync first: 'Requires the task to have an issue (sync it first).' It also gives the intended purpose ('so a later session can backtrack it'), which helps the agent decide when this tool is appropriate, though it does not explicitly describe exclusions or compare with 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 carries the behavioral burden; it discloses a non-trivial ranking algorithm (transitive dependence, dependency-ordered unblockedBy) and the output layout. The 'Answers' framing suggests a non-mutating query, though read-only safety and data freshness are not explicitly stated.

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

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

Two dense sentences deliver question, algorithm, ordering, and output content without filler. The most important information is front-loaded.

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

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

For a read-style tool with an output schema and fully described optional parameters, the description is nearly self-sufficient. It could be stronger by pointing to sibling tools for when a simpler list or ready-task view is needed.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds no details beyond the schema about limit, branch, or project, and does not tie them to the ranking 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 opens with the exact question the tool answers and then specifies the ranking mechanism (transitive wait) and that the first entry is the biggest bottleneck. This clear verb+resource distinguishes blockers from sibling list/read tools even without naming 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?

It provides an explicit trigger ('Answers: what is the biggest blocker right now?') and explains what the ranking is for, giving an agent clear context for when to call it. It does not name alternatives like list_ready or prereqs or state when not to use it, so it stops short of a 5.

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

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

No annotations are present, so the description carries the disclosure burden. It states the core effect (task becomes done) and a notable side effect (the issue is closed), which is meaningful. However, it does not mention reversibility, permissions, or any consequences of the optional branch/project scoping.

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. The parenthetical adds important side-effect information without unnecessary detail, making it perfectly economical for an agent 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 state-transition tool with a self-documenting schema and an output schema, the description is largely sufficient. The only notable absence is explicit usage-context relative to sibling task operations, but the low complexity and strong parameter documentation keep the gap small.

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?

All parameters have full descriptions in the schema, including the opaque nature of project and the optionality of branch. The description adds no additional parameter-level meaning, 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 uses a specific verb ('Mark... done') and a clear resource ('a task'), and adds the side effect 'closes its issue.' This makes it easy to distinguish from siblings like edit_task, start_task, or delete_task.

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 trigger—use this when a task should be marked done—is implied by the description, but no explicit guidance is given about when not to use it or which alternative to prefer. It leaves the agent to infer that this is different from editing or deleting a task.

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. It discloses irreversibility, permanent cascading deletion across layers including the linked GitHub issue, deletion order, and the permission requirement. This is exactly the kind of behavioral context an agent needs before invoking 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?

Two dense sentences with no filler. The critical warning 'PERMANENTLY' and 'Irreversible' are front-loaded, and the alternative tool is named in the same sentence as the warning. Every clause earns its place.

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

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

The description covers the operation's scope, side effects, permission needs, and the safer alternative. With a complete input schema and an output schema present, there is no significant missing context for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains all parameters. The description does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description names the specific verb ('Permanently delete') and resource ('a task and its GitHub issue'), and further clarifies scope ('from every layer, deepest-first'). It clearly distinguishes from the sibling close_task, which is exactly the alternative an agent might confuse it 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?

Explicitly states the key alternative: 'to just mark a task done, use close_task instead.' It also gives a hard precondition (token needs delete-issue permission, repo admin/triage) and a strong signal that this is not for routine completion.

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 disclosure burden, and it does so thoroughly. It states that only passed fields change, that the id is fixed, and that the operation rewrites the issue body and labels. It also reveals the non-obvious label-removal mechanics around clear and default values, which are exactly the behavioral details an agent needs.

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 focused and front-loaded: purpose first, then key constraints, then a separate paragraph for the non-obvious clear behavior. Every sentence contributes necessary operational detail without 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?

Given the tool's complexity — 18 parameters, label side effects, and a sibling with overlapping purpose — the description is complete enough for correct invocation. Hidden behaviors like label rewriting, default-drops-label, and clear-only removal are all covered, and the rich schema handles parameter-level details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that only provided fields are modified and by clarifying the clear parameter's label-removal semantics, which go beyond individual 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?

The description opens with a specific verb and resource: 'Edit any field of a task,' followed by the full field list. It further distinguishes itself from amend_task by noting it 'can narrow scope and edit a done task,' making its purpose and boundaries immediately 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?

The description explicitly contrasts with amend_task, telling the agent when edit_task is the right choice. It also explains when to use the clear parameter for removing fields versus simply setting new values. It could be more explicit about when not to use the tool, but the named sibling comparison provides strong 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?

With no annotations provided, the description must carry the burden of behavioral disclosure, but it only describes output content and does not confirm whether the operation is read-only, has side effects, or requires permissions. The name 'get' implies safety, yet the description itself never states it.

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

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

One sentence, front-loaded with the resource and then enumerating the exact layers returned. There is no filler, redundancy, or wasted wording.

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

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

The tool is simple, has a full output schema, and fully documented optional parameters, so the description does not need to explain return values. However, without annotations or usage guidance, the definition lacks safety context and alternative-routing information, leaving modest gaps.

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

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

The input schema documents both branch and project with 100% coverage, so the baseline is 3. The description adds no parameter-specific meaning beyond mentioning configuration scope; it does not clarify how branch or project affect the layered output.

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 resource (project configuration) and specifies the layered output: CLI flags, global spec, repo override, and effective result. This distinguishes it from siblings like set_config. However, it lacks an explicit verb such as 'retrieves' or 'reads', relying on the tool name for the action.

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

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

The description provides clear context that this tool returns a project's configuration layers, implying it is used when configuration is needed. It does not, however, name alternatives like set_config or state when not to use the tool, leaving the choice 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 burden and does disclose a meaningful behavior: returns null when no task matches the id. It also signals "full record" depth, but it omits any statement about read-only safety, side effects, or how branch/project scoping affects the lookup.

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 concise, front-loaded sentence with no filler. It states the core outcome first and then the edge case, making it easy to parse quickly.

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 required id is documented in the schema and the null behavior is stated, while the output schema covers return values. The description lacks explicit routing to list-oriented siblings and any safety statement, but for a straightforward get-by-id tool this is nearly 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%, and the schema already documents id, branch, and project well. The description adds no additional parameter-level detail beyond tying the id to the null case, which is acceptable given the strong schema coverage.

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

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

The description clearly identifies the resource as "One task's full record" and adds the specific null-if-not-found behavior, so the purpose is immediately clear. It implicitly distinguishes itself from sibling list tools by focusing on a single task, though it does not explicitly name an 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 description implies usage: call with an id to retrieve one task's full record. However, it gives no explicit when-to-use or when-not-to-use guidance, and no sibling alternatives are mentioned, leaving the agent to infer the choice between get_task and list_tasks.

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 and does meaningful work: it discloses the trail's composition (every comment, including people's comments), its ordering (oldest first), and the empty-when-no-issue edge case. These go beyond what the schema conveys. Gaps remain — no statement about behavior for a nonexistent task id, data freshness relative to GitHub (relevant given the sync sibling), or truncation/pagination on very long threads — but the core behavioral traits are covered.

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 and roughly 27 words with zero waste. The core definition is front-loaded, followed by composition/ordering details, then the edge case. Every clause earns its place.

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

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

For a low-complexity getter with 1 required parameter, an output schema, and 100% schema coverage, the description is largely complete: it explains the concept (trail = GitHub issue comment thread), content, ordering, and the empty case. The remaining gaps — error handling for invalid task ids and whether the trail reflects live GitHub state or requires a sync — are minor but non-zero, since they could affect how an agent interprets 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 100%, with all three parameters (id, branch, project) already described inline, so the baseline of 3 applies. The description adds no parameter-level information, though it does give the agent conceptual context for what the id refers to (a task) and why the trail may be empty.

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 precisely defines the resource: "A task's trail: its GitHub issue comment thread, every comment an entry (people's comments included), oldest first." It clearly identifies what the tool returns and its scope (task-specific, not project-wide). It implicitly distinguishes from siblings like get_task (task metadata vs. thread) and append_trail (read vs. write), though it never names a sibling explicitly, which keeps it 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?

Usage is implied rather than stated. The content description makes it clear this is the read-side counterpart to append_trail and that list_*/get_task cover other concerns, but no alternative is named and no explicit when-to-use vs. when-not-to guidance is given. The "Empty when the task has no issue yet" note hints that the tool is only meaningful for tasks backed by a GitHub issue, but that condition is offered as behavior, not as a routing rule.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the task selection criteria and a concrete ordering behavior: 'Resubmitted records come FIRST.' It does not discuss pagination, side effects, or authentication, but for a list operation the core behaviors are reasonably transparent.

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

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

Two sentences with no filler. The first sentence states the core scope, and the second adds the critical ordering rule and an explanatory rationale. 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 list tool with an output schema and two well-documented optional parameters, the description covers membership and ordering sufficiently. It could be more explicit about how this relates to sibling tools, but nothing essential for invoking 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 description coverage is 100%, so the parameters are already fully documented in the schema. The description adds nothing about branch or project, but it does not need to because the schema descriptions are clear and complete.

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 exactly what the tool returns: tasks owned by the planning stage, specifically those never specced or sent back by a build. It relies on the name 'list_planning' for the verb, but the scope and inclusion criteria are specific enough to distinguish it from sibling list tools.

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

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

The description implies when to use the tool — when you need planning-stage tasks — and clarifies that resubmitted replan records are prioritized. However, it does not explicitly state when not to use it or name alternatives like list_ready or list_tasks.

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 and excels. It discloses that the operation is read-only, local, never touches a provider or network, uses the cache file's mtime for updated_at, and that GitHub-only edits show stale stamps until sync. It also states sort order by `project`.

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?

Every sentence earns its place: scope, distinguishing feature, safety, staleness caveat, and ordering. It is information-dense without being verbose.

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

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

For a zero-parameter tool with no annotations and an output schema, the description is complete. It covers what data is returned, where it comes from, semantics of timestamps, sort order, and behavior guarantees (no network, no mutation), fully enabling safe and correct invocation.

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

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

There are zero parameters, so the schema is empty and the description adds meaning by explaining that taking no project is intentional and signals server-level scope. This helps an agent understand why no parameters are needed.

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

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

The description clearly states the tool lists every cached project with task counts and last-changed time. It explicitly differentiates itself by noting it is the ONE tool that takes no `project` parameter and answers about the server itself, distinguishing it from all sibling tools.

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

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

It explains when to use the tool: to enumerate what projects exist locally, e.g., for a console to list without requiring a human to type paths. It doesn't explicitly name sibling alternatives one might choose instead, but the server-level vs project-level distinction makes usage 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 carries the full burden, and it delivers richly: it explains the ranking formula, why in-progress tasks are excluded, how scope containment works, how overlap across lanes is computed, that claims are never auto-released, and how stale claim ages behave. This is far beyond a minimal 'lists ready tasks' statement and gives an agent the behavioral detail needed to interpret and act on the response safely.

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 long but structured with front-loaded purpose and clear field-by-field paragraphs. Most sentences earn their place by explaining decision-relevant behavior, though some explanatory asides like the full dispatcher sweep example and edit_task release path could be trimmed without losing core meaning.

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 tool's selection criteria, ranking logic, response fields, scoping behavior, overlap semantics, labels, and claim staleness handling. With no annotations and a rich output contract, this level of detail gives an agent everything needed to call the tool correctly and interpret its results without additional lookups.

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 meaningful semantics for the `scope` parameter: folder containment rules, no-scope means every lane, and the connection to lane-based dispatching. It does not add extra meaning for `branch` or `project`, but those are already clearly described in the schema, so the added scope detail justifies above baseline.

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

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

The description opens with a specific verb+resource: it lists tasks that are ready to build, defined as open, settled, and with all dependencies done. It clearly differentiates from siblings by focusing on ready-to-dispatch work rather than general task listing or planning. The ranking behavior and exclusion of in-progress tasks further pin down its unique purpose.

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

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

The description provides clear context for when to use the tool: when a dispatcher needs tasks that are safe to build immediately, and when scoping to a lane to avoid overlapping workers. It does not explicitly name sibling tools or say 'use list_tasks for all tasks,' but the ready-to-build framing and dispatch-oriented examples make the intended usage 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?

Since no annotations are provided, the description carries the behavioral disclosure burden. It clearly communicates scope behavior: full records, whole graph, and both open and done tasks. It does not describe auth, rate limits, or pagination, but for a straightforward read/list tool it provides meaningful behavioral context.

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

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

The description is extremely compact and front-loaded: it states scope, record detail, status coverage, and sibling alternatives in two short clauses. Every word contributes to selection and invocation decisions.

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 combined with the fully documented schema and output schema is sufficient for correct tool selection and invocation. It clarifies when to choose list_tasks versus its closest siblings, and the optional parameters are adequately explained in the schema.

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

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

Both parameters (branch and project) are already fully documented in the schema, including the note that the backend decides how branch is used and that project has a server default. The description adds no parameter-level semantics, so the baseline of 3 applies because the schema coverage is complete.

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 exactly what the tool returns: every task as full records across the whole graph, including open and done tasks. It also distinguishes the tool from its siblings by naming list_ready/list_planning and get_task as alternatives, so an agent can select it without ambiguity.

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

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

It gives explicit routing guidance: use list_ready/list_planning for scannable working subsets and get_task for a single task. By implication, list_tasks is the tool for exhaustive, full-graph retrieval, which is clear and actionable.

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 burden of behavioral disclosure. It does explain ordering semantics and the meaning of startable=true, which is useful. However, it does not explicitly state whether the operation is read-only, how errors are handled, or what happens for unknown or invalid task ids.

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

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

The description is concise and front-loaded. The usage question appears first, followed by the output shape and the meaning of startable=true. Every sentence contributes necessary information without 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?

An output schema exists, and the description covers the key return semantics: dependency-ordered layers and the startable flag. For a low-complexity, single-required-parameter tool, this is largely sufficient. It could mention edge cases like cycles or empty prerequisite sets, but startable=true largely handles the empty 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?

Schema description coverage is 100%, so the parameters (id, branch, project) are already documented in the schema. The description does not add additional parameter-level nuance beyond the core concept of 'the task you want to start,' so the baseline of 3 applies.

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

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

The description clearly identifies the tool's purpose: it answers what must be done before starting a task and returns open prerequisites as dependency-ordered layers. It also distinguishes itself from likely sibling tools by introducing a concrete output structure (work layer 1 first) and the startable flag.

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 opening phrase, 'to start working on this task, what has to be done first?', gives a clear usage context: call this before starting a task to identify prerequisites. It does not explicitly mention alternatives or when not to use it, but the intended scenario is obvious.

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 behavioral burden. It credibly explains that progress is derived from tasks and cannot go stale, and frames the tool as a read-before-work reference, implying no mutation. However, it does not explicitly state read-only behavior or address side effects, auth, or rate limits.

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

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

Three focused sentences with no filler: the first front-loads the output contents, the second explains why the data is trustworthy, and the third gives usage context against a sibling tool. 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?

The description covers the main output dimensions, the derivation guarantee, and when to use it, while the output schema handles return details and optional parameters are documented in the schema. The only notable gap is the lack of an explicit read-only/side-effect statement, which matters more because no annotations are present.

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

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

Schema description coverage is 100%, and both branch and project already have meaningful descriptions in the schema. The tool description itself adds no parameter-level semantics; it focuses on output derivation and usage context, 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 states precisely what the tool returns: per-target task counts by status, ready-to-dispatch tasks, targets it waits on, and targets waiting on it, in dependency order. It also distinguishes itself from list_ready by clarifying that roadmap is target-centric rather than task-ranking.

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 says to read this before choosing work and contrasts it with list_ready: list_ready ranks tasks, while this tool shows which target tasks serve and which rows gate releases. This gives the agent clear, actionable 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 carries the behavioral burden. It does disclose important failure behaviors: it errors on dependency cycles and errors when a dependency outside the target has not shipped. It also explains target self-containment. However, it does not state whether the operation is read-only, whether it has side effects on the plan, or how it treats the branch/project scoping beyond the schema descriptions.

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

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

The description is three sentences with no filler. The core idea is front-loaded, and each subsequent sentence adds important information about scoping and error behavior. It is compact enough for an agent to parse quickly while still carrying substantive guidance.

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 required parameters and an output schema, the description covers the main operational concerns: dependency ordering, cycle errors, target scoping, and mis-scoping indicators. The main gaps are that 'open plan' is used as a domain term without a brief definition, and the relationship to sibling planning tools is not addressed. Overall it is sufficiently complete for the agent to invoke the tool correctly in the target-scoped 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially for `target`: it explains that the scoped result is the build read set and that a target ships as one self-contained stack. It does not add much about `branch` or `project`, but those are already well 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 presents the tool's output — the open plan represented as dependency-ordered layers — and explains the target-scoping behavior. It is not a tautology, and it is specific enough to distinguish 'schedule' from mutation-style siblings, but it does not use an explicit verb like 'returns' or 'computes', and it does not differentiate itself from closely related planning tools such as list_planning or prereqs.

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 guidance on when to pass `target` ('to scope it to one roadmap target') and explains what the scoped result means ('what a build dispatched that target should read'). It also explains an error condition that reveals misuse ('a dep outside the target that has not shipped ... means the target is mis-scoped'). However, it does not explicitly state when to prefer this tool over sibling planning/list 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?

With no annotations, the description carries the behavioral burden, and it delivers: it discloses that settings propagate to every provider layer and that repo scope overrides global for a single repo. It could add more about merge-vs-replace semantics or return/error behavior, but the core side-effect profile is clearly stated.

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 contain the essential behavioral model and scope semantics with no fluff. The central propagation fact is front-loaded, and the global/repo override rule follows immediately.

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 setter with a rich nested schema and an output schema, the description plus schema is sufficient to call the tool correctly. Minor gaps are the lack of explicit mention that config is merged (though the schema says 'settings to merge in') and no direct guidance on branch/project parameters, but those are documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantic value by explaining what scope=global and scope=repo actually do, which the schema's generic 'Where the settings apply' does not. It does not re-describe every config key, which is appropriate since the schema already documents them.

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

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

The description opens with a specific verb and resource ('Configure preferences') and immediately clarifies the central, propagating nature of the operation. The scope=global vs scope=repo distinction makes the tool's behavior and scope unmistakable and differentiates it from the read-only get_config sibling.

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 context for when to choose global vs repo scope, including the effect of each ('writes the spec that applies to all repos' vs 'overrides it for this repo only'). It does not explicitly name alternatives or exclusions, but the usage context is strong enough for an agent to apply it correctly.

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 clearly states the side effects: the task leaves list_ready, the board card moves to In Progress, and the state is released when the task is closed or sent back to spec:replan. It does not cover idempotency or error cases, but the core behavioral contract is well explained.

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

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

The description is two sentences and every clause adds value: it defines the action, places it in the workflow, and explains the resulting state transitions. The core action is front-loaded, and the self-clearing behavior is included without unnecessary 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?

Given the existence of an output schema and the straightforward nature of the tool, the description covers the essential context: what happens to the task, how it interacts with list_ready, and how it is released. It could mention error conditions or prerequisites (e.g., task must currently be in list_ready), but it is sufficiently complete for an agent to invoke it correctly in the normal workflow.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (id, branch, project). The description does not add parameter-level meaning beyond what the schema provides, 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 opens with a specific verb and resource — 'Mark a task in progress' — and immediately clarifies it as the first action a worker takes. It further distinguishes itself from sibling tools by explaining the task leaves list_ready and later can be released via close_task or spec:replan, so an agent knows exactly what this tool is for.

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 the tool: it is the first thing a worker does when picking up a task, and it removes the task from list_ready so it is not dispatched twice. It does not explicitly name alternative tools or list when not to use it, but the workflow positioning and state-change explanation provide strong practical 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 carries full responsibility for behavioral disclosure. It does disclose the two main actions—pulling issues and pushing seed tasks—but it does not mention whether the local cache is overwritten, whether authentication or network access is required, or whether the operation is safe to repeat.

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. The main action 'Reconcile the repo with GitHub' comes first, followed by the two concrete effects, making it easy for an agent to parse quickly.

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

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

An output schema exists, so return values do not need explanation, and both parameters are fully documented in the schema. However, for a sync operation with no annotations, the description omits important context such as side effects on the existing local cache, external dependencies, and failure modes, leaving notable gaps.

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

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

The input schema already provides 100% coverage for both parameters, so the description does not need to add parameter details. It adds no param-specific meaning beyond the schema, 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 uses a specific verb and resource ('Reconcile the repo with GitHub') and lists two concrete actions: pulling issues into the local cache and pushing seed tasks. This clearly distinguishes the tool from sibling task-management tools like add_task or edit_task.

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 'Reconcile the repo with GitHub' gives clear context for when this tool is appropriate: synchronizing local state with GitHub. It does not explicitly name alternatives or list when-not-to-use cases, but the intended use case is clearly communicated.

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