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

No annotations are provided, so the description carries the full burden. It does disclose a meaningful behavioral trait — first-accept-wins semantics that prevent duplicate work — which is valuable. But it omits what happens on a losing claim (error vs. no-op), idempotency, and any auth requirements for agentId.

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?

A single front-loaded sentence with no filler; the parenthetical efficiently conveys the concurrency rationale. Nothing is wasted.

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

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

An output schema exists, so return values need not be described, and the core concurrency rationale is present. The main gap is the failure path when a task is already claimed, which is central to the 'first accept wins' framing but never spelled out.

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

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

Schema coverage is 0% and the two required parameters (taskId, agentId) have no schema descriptions. The description implies a task identifier but says nothing about agentId — whether it is the claiming agent's own identity or something else — so it does not compensate for the coverage gap.

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

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

States a specific verb (claim) and resource (delegated task) plus the scope of the operation, so it is distinct from release_claim and complete_claim. It stops short of naming a sibling by name, so differentiation requires a bit of inference from the sibling list.

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 'before working on it' gives timing guidance (claim precedes work), which implies when to call it. However, it never addresses alternatives such as check_collision, claim_intent, or complete_claim, nor when-not to call it, leaving routing 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 discloses an important trait, that no claim is registered, but omits permissions, side effects beyond claim registration, validation behavior, and whether any state is mutated.

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

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

It is a single, front-loaded sentence with no wasted words. The dry-run constraint is placed after the core action, keeping the purpose immediately clear.

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

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

For an 8-parameter tool with no annotations and no parameter documentation, this one-sentence description is incomplete. The output schema may cover return values, but the description says too little about inputs, collision semantics, and required context.

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 has 8 parameters with 0% description coverage, and the description names none of them. It does not explain repo, branch, files, symbols, or the other inputs that determine collision checking.

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: 'Check for collisions.' It also distinguishes this tool from claim-registering siblings with 'without registering a claim (a dry run),' so an agent can tell it apart from claim_intent without inspecting schemas.

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

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

The dry-run phrasing clearly implies when to use this tool: to check collisions before or instead of registering a claim. However, it does not explicitly name the alternative tool or state when registration is required, so some inference remains.

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, so the description carries the full burden and does so well: it discloses collision reporting, that Tower notifies on read changes and shows old/new signatures, that `declares` hands a contract to parallel agents, and the refusal response shape (`alternatives`, `avoid`). It omits auth/permission and rate-limit behavior, keeping it from a 5.

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

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

Front-loaded with the core action and effect, then elaborates on reads/declares/refusal. It is a long single paragraph, but nearly every sentence conveys actionable behavior rather than 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?

An output schema exists, so return values need no explanation, and the collision/refusal behavior is described. However, for an 11-parameter tool with 0% schema documentation, the roles of `files` vs `symbols`, `force`, and `etaMinutes` are left to inference, leaving gaps an agent must still resolve.

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

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

Schema coverage is 0% across 11 parameters, so the description must compensate. It explains the subtle `reads` and `declares` semantics well (including example syntax), but leaves central parameters like `files`, `force`, `purpose`, `etaMinutes`, `repoId`, and `projectId` entirely undocumented. Partial compensation for a large parameter surface.

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

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

States a specific verb+resource ('Register intent to edit code') and its primary effect ('Returns any collisions with other active agents'). The intent is unambiguous and distinguishable from adjacent siblings like release_claim or propose_intent. It stops short of explicitly naming the sibling it differs from, so it lands at 4 rather than 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?

Strong temporal directive: 'Register intent to edit code BEFORE editing' and 'Call this first, always.' It also gives an explicit fallback path for refusal ('work outside avoid; Tower messages you when it frees up'). It does not name alternative tools (e.g. record_reads vs the reads param), so it is clear context without explicit tool 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 full burden. It does disclose a meaningful side effect: every agent reading a changed declaration is notified of the final signature and whether it matches the declaration. But it says nothing about what releasing the claim actually mutates, whether it is reversible, auth/permission needs, or failure 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?

Two sentences, action front-loaded, no filler. The second sentence is somewhat tangled ('is told what it landed as'), but it earns its length by disclosing the cross-agent notification 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?

An output schema exists, so return values need no explanation, and the core payload semantics are covered. For a state-mutating claim operation with zero annotations, though, the description should say more about the effect on claim state and how it differs from release_claim.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for two params: it explains that symbols should carry the final sig/sigText (not just any value) and that commitSha is optional. claimId is left implicit, which is the only real gap.

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

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

States a specific verb+resource (release a claim) and a precise trigger (after committing, optionally recording commitSha). It does not, however, name or differentiate itself from the near-identical sibling release_claim, which an agent would reasonably confuse it with from name alone.

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

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

Gives a clear timing condition — use it after you have committed — and notes that recording the commit sha is optional. It stops short of the 5-level bar because it never states a when-not or points to release_claim as the alternative for the non-commit case.

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 does disclose one important side effect ("Auto-notifies the delegator"), which is real added value, but it omits permissions/auth requirements, idempotency (what happens if called twice), and error behavior for tasks not in an accepted state.

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?

A single dense sentence with zero filler. The core action is front-loaded and the side effect is appended, so nothing is wasted.

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

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

An output schema exists, so return values need not be described. Still, for a 7-parameter mutation tool with zero annotation coverage and no parameter descriptions in the schema, the definition leaves too much unspecified — notably identifier semantics, filesChanged, and failure/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?

Schema description coverage is 0%, so the description must compensate. It explains result, commitSha, prUrl, and success (including the default-true semantics implied by "success or failure"), covering the most ambiguous fields, but it says nothing about the required taskId/agentId or filesChanged, leaving three parameters undocumented everywhere.

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

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

States a specific verb and resource ("Finish an accepted task") plus the outcome semantics (success or failure) and the artifacts carried back (result, commit sha, PR url). It does not distinguish itself from the close sibling complete_claim, which an agent could easily confuse with this tool, so it falls 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?

"an accepted task" implies the precondition that the task was previously claimed/accepted, which is useful routing context. However, it never states when not to use it or names complete_claim as the alternative, so the usage guidance is only implied rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the critical side effect that reading marks messages read. However, it says nothing about whether it drains all messages or a page, error behavior, or what happens to already-read messages when unreadOnly is defaulted.

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, action first and trigger second, with zero filler. Every clause carries information an agent needs.

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

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

An output schema exists so return values need not be explained, and the when-to-call guidance is complete. But for a five-parameter tool with no annotations and no parameter documentation, the definition leaves the agent guessing about scoping inputs.

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

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

Schema description coverage is 0% across five parameters, so the description must compensate and instead adds no parameter meaning whatsoever — nothing about agentId/repo/repoId/projectId scoping or what unreadOnly=true (the default) means. Only the side-effect note tangentially hints that read messages are affected.

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

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

States a specific verb and resource ('Read your inbox') and even flags the side effect in parentheses, so the agent knows exactly what the operation is. It stops short of explicitly distinguishing itself from other read-oriented siblings like pending or get_decisions, but the inbox framing is clear enough to route on.

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

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

Gives a concrete, executable trigger: 'Call whenever claim_intent reports unreadMessages > 0.' It names the sibling tool that produces the condition and the exact field value that selects this tool, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read/recall operation, but says nothing about scoping behavior when all six optional filters are omitted, result limits/ordering, or the cost of an unfiltered query.

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 single short sentence is front-loaded and free of waste, but for a tool with six undocumented and overlapping filters it is undersized rather than concise — there is room to add distinguishing detail without bloat.

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-value documentation is not owed. Still, given six optional parameters with zero coverage and no annotations, the description leaves the invocation mechanics (which filters to combine, what an unfiltered call returns) entirely unresolved.

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 six parameters have 0% schema description coverage and the description mentions none of them. The schema exposes ambiguous pairs (repo vs repoId, projectId, tags vs relatedFiles vs query) with no explanation of how they interact or which to prefer, leaving the agent to guess.

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 ('Recall past architecture decisions'), which is much clearer than a tautology. However, it never distinguishes this tool from its sibling log_decision, the obvious write-side counterpart, so an agent must infer the read/write split from names alone.

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?

'before acting' supplies a temporal trigger for use, which is more than nothing, but there is no statement of when not to use it, no mention of the log_decision sibling, and no guidance on which parameters are needed for which retrieval scenario.

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 usefully discloses auto-expiration and explains what `invalidations` means, but it omits TTL behavior, failure modes, ownership requirements, and what happens when the claim is already invalid.

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 first sentence front-loads the core purpose, and the second explains the return payload. The description is dense but well-structured, with no obviously wasted sentences.

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

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

The tool is simple, has an output schema, and the description covers its basic purpose and return meaning. Still, it lacks usage cadence, parameter sourcing, and key behavioral details that would help an agent call it correctly without additional context.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented `claimId` parameter. It only implies that the claim must be active; it does not explain where `claimId` comes from, its format, or how to obtain one.

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: keeping an active claim alive. It distinguishes the action from mere claim creation or release, but it does not differentiate this tool from its sibling heartbeat_worker.

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 implies when to use the tool by warning that claims auto-expire without heartbeats. However, it gives no explicit guidance on frequency, timing, prerequisites, or when to prefer a sibling such as heartbeat_worker.

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 discloses the cadence (every poll) and the observable effect (board shows live presence), but omits idempotency, permission requirements, and what happens if the call is skipped or fails.

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?

A single front-loaded sentence with a compact parenthetical for usage cadence. Every clause earns its place, and there is 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 output schema exists, so return values need not be explained. However, for a tool with six undocumented parameters and no annotations, the description is too thin on parameter meaning and operational prerequisites to let an agent call it correctly without inspecting 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 description coverage is 0% across six parameters, and the description adds no meaning for any of them. Required fields (agentId, repo), the status enum (ok/low), and optional fields like runner and projectId are left entirely unexplained.

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: announce that this worker is online and ready to run tasks. It also clarifies the effect on the board. It does not differentiate itself from the sibling `heartbeat` tool, leaving some ambiguity about which to use.

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

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

It explicitly says to call the tool every poll so the board shows live presence, which gives clear usage cadence. It does not say when not to use it or mention any alternative tools like `heartbeat`.

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; the verb 'List' implies a non-destructive read, which is the key trait. It says nothing about ordering, pagination, or limits, though the presence of an output schema removes the need to explain return values.

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?

A single compact sentence with the core action front-loaded and the modifiers trailing. Nothing redundant or wasted.

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

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

Output schema exists so return values needn't be described, and the tool is a simple list operation, lowering the bar. Still, two of five filter parameters are undocumented and there is no guidance on ordering or result size, leaving gaps for a zero-annotation tool.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate, yet it only names repo, branch, and status. The repoId and projectId parameters are completely undocumented in both schema and description, and no filter semantics (AND vs OR, enum behavior) are explained.

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

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

States a specific verb+resource ('List claims') and names the filterable fields, which is clear on its own. However, it offers no differentiation from siblings such as list_tasks or get_decisions, so an agent cannot tell from the description alone why it would pick this over those.

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?

'optionally filtered by repo/branch/status' implies the use case (browse claims with optional narrowing), but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool. Usage is inferable but not 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?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies read-only behavior and 'poll' implies repeated retrieval, but the description omits permissions, rate limits, pagination, or side-effect details.

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 wasted words. It states the verb, resource, filter dimensions, and usage context efficiently.

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 six-parameter tool with no annotations and 0% schema description coverage, the description is too sparse. An output schema exists so return values need not be explained, but missing parameter semantics and usage guidance leave significant 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 description coverage is 0%, so the description must add parameter meaning. It maps repo, status, recipient, and assignee to four of the six parameters, but omits repoId and projectId and does not explain optionality or the distinction between similarly named filters.

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

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

States a clear verb ('List'), resource ('delegated tasks'), and filter dimensions. The parenthetical '(the worker's poll)' adds a usage context. It does not explicitly distinguish itself from siblings like list_claims or next_task, so it falls 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 worker's poll' implies the context in which this tool is used, giving some usage guidance. However, it provides no explicit when-to-use, when-not-to-use, or alternative-sibling guidance, which leaves the agent to infer selection behavior.

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 behavioral burden and mostly fails to: it does not say whether records are permanent, whether duplicates are merged, whether teammates are notified, or what identity requirements the author field implies. 'Shared memory' does disclose that the entry is team-visible, which is the only real behavioral signal.

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?

A single sentence, front-loaded with the action and resource, with zero filler. The rationale emphasis is delivered compactly.

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 need no explanation, but for an 8-parameter mutation tool with no annotations and no schema descriptions, the description is far short of what an agent needs. It omits parameter mapping, required-field implications, and any behavioral consequences of writing to shared memory.

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

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

Schema description coverage is 0% across 8 parameters (title, author, body, repo, repoId, projectId, tags, relatedFiles), and the description mentions none of them. The emphasis on 'WHY' loosely implies what belongs in body, but title/author being required and the id-vs-name distinction between repo and repoId are left completely unexplained.

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 and resource ('Record an architecture decision') and adds the distinguishing nuance that the rationale ('WHY') is captured too. It implicitly contrasts with the read-side sibling get_decisions, though it never names that sibling explicitly.

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 when-to-use or when-not-to-use guidance, and no alternative is named despite get_decisions existing in the sibling set. 'For the team's shared memory' hints at intent but leaves the triggering condition for logging a decision entirely 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 hints at sequencer coordination and module-safety, but does not disclose whether fetching reserves/locks the task, what happens when no safe task exists, whether it mutates state, or any auth requirements.

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?

A single, front-loaded sentence with no filler. Every word contributes to conveying the tool's action and selection criterion.

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 output schema covers return values, so that need not be explained. But for a coordination tool with five undocumented params and zero annotations, the description omits essential context about inputs and side effects, leaving the agent under-informed.

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?

Five parameters with 0% schema description coverage and no parameter explanation in the description. The phrase 'whose module is safe' loosely gestures at the module concept likely tied to the 'candidates' array, but required inputs agentId and repo, and optional repoId/projectId/candidates, are entirely unexplained.

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 ('Ask the sequencer for a task') and adds a meaningful qualifier ('whose module is safe to start right now'), which conveys collision-aware selection. It does not explicitly differentiate itself from potentially overlapping siblings like pending, list_tasks, or accept_task, so it stops 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: an agent should call this when it wants to begin work and needs a task that won't collide. However, the description never says when to prefer this over pending, list_tasks, or accept_task, nor does it state prerequisites or 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 full burden and does disclose the key behavioral trait: 'Read-only ... Marks nothing read,' making the side-effect-free nature explicit. It does not cover auth requirements, scoping, or rate limits, but the most important behavioral fact (it is a non-mutating nudge) is front and center.

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

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

Two tight sentences, front-loading the read-only count semantics and then the follow-up routing. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need not be explained, and the '> 0' condition hints at the count. However, the four undocumented filter parameters leave a real gap for an agent deciding how to scope the call, so it is only minimally 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?

Four parameters (agentId required, plus repo, repoId, projectId) have 0% schema description coverage, and the description explains none of them. Whether the count is scoped by repo/project is left entirely to inference, so the description fails 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 states a specific verb+resource: a read-only count of unread messages and open tasks. It implicitly distinguishes itself from the listing siblings (fetch_messages/list_tasks) by framing itself as a count/nudge rather than a full read. It does not explicitly name itself against those siblings, but the purpose is unmistakable.

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

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

It gives a clear conditional trigger: 'if it returns > 0, call fetch_messages / list_tasks,' routing the agent to the correct follow-up tools. It stops short of stating when not to use it (e.g., when you already know you need full content, skip the count), so it is clear context without explicit 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 full burden. It discloses what comes back (anyone already doing the same work, semantic matching) and a cost/ordering trait, but leaves unresolved whether the call registers durable state, whether it mutates anything, or whether repeated calls are idempotent — key behavior for a 'propose' 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 dense sentences with the imperative timing constraint front-loaded. Every clause adds routing or behavioral information; nothing is 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?

An output schema exists, so return values needn't be explained, and usage timing is well covered. However, with zero annotation coverage and five undocumented parameters, an agent still lacks guidance on what the identifier fields mean and whether the call has side effects.

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

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

Schema description coverage is 0% across 5 parameters (agentId, repo, repoId, purpose, projectId). The description only loosely implies the purpose field via 'say in plain English what you plan to work on' and says nothing about repo, repoId, projectId, or agentId semantics, so it fails 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 gives a concrete verb and resource: state in plain English what you plan to work on before researching or writing. It also distinguishes the matching behavior ('matched on meaning rather than file paths') from path-based checks, though it never names the sibling tools (claim_intent, check_collision) it sits beside.

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 the timing condition clearly ('BEFORE you research or write anything'), the call frequency ('One call per task'), and the value rationale ('cheapest check', 'fires before your tokens are spent'). It stops short of naming explicit alternatives or when-not-to-use cases.

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 and does well: it discloses this is a recording/mutation step, that it returns `conflicts` immediately when a peer is editing what you read, and why that timing matters. It doesn't cover auth, idempotency, or error behavior, but the output schema covers the return shape.

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

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

Three tight sentences: purpose first, the payoff (early conflict detection) second, the operational caveat last. Every sentence earns its place with no filler.

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

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

The output schema covers return values, and the description explains the tool's role in the coordination loop well. But for a 6-parameter coordination tool with 0% parameter coverage, an agent still lacks semantic grounding on the required and identity fields.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and does not. Only 'declarations you just read' loosely maps to the `reads` payload; repo, repoId, branch, agentId, and projectId receive no explanation anywhere.

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

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

States a specific verb and resource ('Record declarations you just read') and immediately frames its role in the workflow by naming the sibling it feeds into (claim_intent). An agent can tell this apart from check_collision or claim_intent without opening the schema.

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

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

Gives explicit routing guidance: 'Normally called by the PostToolUse hook, not by you,' which is a strong when-not-to-call signal. It lacks a stated condition for when an agent should call it manually, but the negative guidance is unusually valuable.

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, yet it only states 'abandon' with no mention of side effects (does the claim get freed for others?), required permissions, reversibility, or failure modes. An output schema exists so return values need not be described, but the mutation semantics remain opaque.

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?

A single short sentence that is front-loaded and wastes no words. It is arguably too terse to be complete, but from a pure conciseness standpoint it is efficient.

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 state-mutating claim operation with no annotations, no parameter documentation, and many sibling claim-related tools, the description is too thin. An agent cannot tell what happens to the claim on release or how it differs from complete_claim.

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

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

There is one parameter (claimId) with 0% schema description coverage, so the description must compensate and does not — claimId is never mentioned or explained. This leaves the single required parameter undocumented in both schema and 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 gives a clear verb (abandon/release) and resource (claim) and the qualifier 'without committing' hints at the distinction from the sibling complete_claim. It does not explicitly name alternatives, 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?

No when-to-use guidance is provided and the sibling tools (claim_intent, complete_claim, list_claims) are never referenced. The phrase 'without committing' vaguely implies a distinction from committing flows, but the agent must infer when to choose this over complete_claim.

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 usefully discloses that the task is parked (execution blocks until approval) and that approval happens out-of-band by a person from the board/phone. It omits denial/timeout behavior, whether the call is idempotent or re-requestable, and what the caller should do while waiting.

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?

A single front-loaded sentence with the blocking behavior stated first and the approval channel in the trailing clause. No filler, though the parenthetical and em-dash aside make it slightly less crisp than it could be.

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 need not be described. For a two-parameter workflow tool with no annotations, the definition still leaves gaps around the approval lifecycle (how to poll, resolve, or what happens on rejection), which an agent needs to use it end-to-end.

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

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

Schema description coverage is 0% and the description adds no parameter meaning at all. It is not clear whether agentId is the requester's own identity or the approver, nor whether taskId must already be claimed. The self-evident names are the only guide.

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 parks a task for human approval rather than executing it. That clearly separates it from executing siblings like complete_task or next_task. It does not explicitly name a sibling such as resolve_approval, so it stops 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?

"before running it (remote-approve worker mode)" gives implied usage context — this tool is for workers configured to request remote approval. However, it never says when not to use it, what the alternative path is, or how the approval is later resolved (resolve_approval) or checked (pending).

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 is a mutation tool, yet it does not say what happens to the task on approval vs rejection, whether the change is reversible, what permissions are required, or what error occurs on an already-resolved task. The actor note is the only extra 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?

A single front-loaded sentence with no filler. Efficient, though the parenthetical is arguably the least informative clause placed last.

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 need not be described, but for an unannotated mutation tool with zero parameter descriptions the definition is too thin: an agent learns neither the preconditions nor the side effects of resolving an approval.

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

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

Schema coverage is 0%, so the schema documents neither parameter. The description's 'approve or reject' does map clearly onto the `approved` boolean, but `taskId` is left entirely unexplained. Partial compensation for a low-coverage 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?

States a specific verb+resource: approving or rejecting a 'parked task'. This is distinguishable from the sibling request_approval as the resolution side of the flow, though the description never names that sibling or defines what 'parked' means.

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 'used by the board; also callable by tools' describes who calls it, not when to call it or what preconditions must hold (e.g., whether a pending approval request must already exist). No alternative or exclusion is given relative to request_approval.

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, so the description carries the full burden. It usefully discloses async delivery semantics ('delivered on their next Tower contact') and the task/reply protocol, but says nothing about auth, failure behavior for unknown agents, rate limits on broadcast, or delivery guarantees.

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 that front-load the core action and broadcast capability, then the delegation/reply protocol. No filler, though the second sentence packs two ideas together.

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 need no explanation, and the async-delivery model is conveyed. But with 9 parameters, 0% schema coverage, and no annotations, several parameters and behaviors remain undocumented for an agent to call this correctly.

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

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

Schema coverage is 0% across 9 parameters, so the description must compensate. It clarifies toAgentId (including '*'), the kind enum, and replyTo, but leaves body, repo, fromAgentId, size, repoId, and projectId entirely unexplained, covering only about a third of the surface.

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

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

States a specific verb+resource ('send an async message or task to another agent') and clarifies the '@*' broadcast target. The send/receive split from sibling fetch_messages is inferable, but no sibling is named explicitly, so it falls 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?

Explains how to use the tool's modes: kind 'task' delegates work and should be answered with kind 'task_update' (replyTo=task id). This gives clear in-tool usage guidance, though it does not contrast with sibling tools like accept_task/complete_task.

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