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

No annotations are provided, so the description carries the burden. It does disclose a behavioral trait: the response excludes history, directing to get_task for that. However, it does not mention side effects (e.g., whether the task state changes irreversibly), required permissions, or idempotency. Some context is added, but significant gaps remain.

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

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

The description is two concise sentences that front-load the primary purpose and then add a useful behavioral note. Every word earns its place with no redundancy or filler.

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

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

Given the tool has 4 parameters, no output schema, and no annotations, the description provides some essential context (caller, timing, return format limitation) but omits details on parameter semantics for half the parameters and the state transition side effects. It is adequate but not complete.

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

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

With schema description coverage at 0%, the description must compensate. It implicitly clarifies 'by' as the creator/reviewer and suggests 'id' refers to the task, but it does not explain 'note' or 'expected_version'. The compensation is partial and insufficient for four parameters.

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

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

The description clearly states the tool's purpose with a specific verb ('Approve') and resource ('a completed task'), and distinguishes it from sibling tools like complete_task or request_revision. It also adds context on the typical caller (creator/reviewer) and contrasts with get_task regarding history.

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 ('after checking the implementer's work') and mentions an alternative for a specific need ('call get_task for that' regarding history). It lacks explicit exclusions or a direct comparison to all siblings, but the guidance is helpful.

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 transparency burden. It discloses the state precondition and the return payload shape, but it does not mention side effects, error/conflict behavior, or the role of expected_version. These are material gaps for a mutation tool, though the description is not misleading.

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 exactly two sentences, front-loaded with the core action and state restriction, and then a useful pointer to get_task. Every word earns its place, with no repetition or filler.

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

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

For a simple cancel operation, the description covers the basic purpose and return shape, and the get_task pointer is helpful. However, the lack of parameter semantics and conflict/error behavior, combined with the absence of annotations and output schema, leaves the tool only marginally adequate for safe autonomous 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?

Schema description coverage is 0%, and the description provides no explanation of id, by, reason, or expected_version. The agent must infer meaning solely from parameter names and schema constraints, leaving important semantics like optimistic concurrency undocumented.

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 action ('Cancel a task') and the resource (a task), and it adds a meaningful state constraint ('not already completed/approved/cancelled'). It also distinguishes itself from get_task by noting that the returned summary omits history[], which helps agents pick the right sibling tool.

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 describes the valid use case: canceling a task that is not in a terminal state. It also points to get_task as an alternative for retrieving history. However, it doesn't go further to explain when cancel_task should be chosen over other mutation siblings or what to do if the task is already claimed or in progress.

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 fully carries the burden. It discloses atomic claim behavior, skips pre-assigned tasks, returns null if no eligible task, and notes the absence of history[] while directing to get_task. This is transparent about side effects and 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?

Two sentences, front-loaded with the core purpose, followed by relevant details. No wasted words and all information is actionable.

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 moderate complexity, no annotations, and no output schema, the description covers the key behavioral aspects, return value, and points to get_task for additional detail. It is complete for an agent to decide when and how to invoke it.

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

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

The schema covers one parameter (assignee) with a clear description, and the description adds meaning for 'tag' by noting it is optional and filters eligible pending tasks. Both parameters are effectively documented, though the description could have explicitly mentioned the assignee parameter as well.

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's function: 'Atomically claim the first eligible pending task' and distinguishes it from siblings by mentioning the alternative of a separate list_tasks + claim_task round trip. This is a specific verb+resource with clear scope.

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

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

The description explicitly says to use this tool 'instead of a separate list_tasks + claim_task round trip', which provides clear context for when to use it over alternatives. It also points to get_task for retrieving history, but does not explicitly state when not to use it (e.g., when a specific task ID is known).

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 exist, so the description carries the full burden. It discloses the failure behavior ('Fails if the task was pre-assigned'), the return value ('Returns the task summary'), and explicitly notes the absence of history, pointing to get_task. This is meaningful beyond schema but lacks details on permission requirements or state-change implications.

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

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

Two sentences, front-loaded with the main action, no wasted words. The failure and return-info additions are purposeful.

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 three params and no output schema, the description covers the core behavior, failure mode, and return format. It even directs users to get_task for history, covering a common follow-up. The only missing context (expected_version usage) is already 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?

The schema already documents assignee and expected_version with descriptions, but the id parameter only has a pattern. The description adds no parameter-specific guidance, leaving id's semantics implicit. With 67% schema coverage, the description doesn't compensate for the un-annotated id, but schema covers the rest.

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+role: 'Claim a pending task as the implementer working on it.' It clearly distinguishes from siblings like claim_next_task and create_task by indicating this targets a specific pending task. The failure condition (pre-assigned) adds useful purpose detail.

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: when an implementer wants to claim a specific pending task. It also provides an alternative for history: 'call get_task for that.' However, it doesn't explicitly contrast with claim_next_task or state when not to use, so it's clear context but missing 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 behavioral disclosure burden. It usefully states that the tool returns the task summary without history and directs to get_task for that. But it does not mention permissions, reversibility, or potential errors like version mismatch, leaving some significant behavioral gaps.

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 concise sentences: the first states the action and scope, the second reveals return behavior and points to an alternative. Every word earns its place, with no redundancy.

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

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

The description does a good job for a simple state transition, covering action, eligible states, and return format. However, it lacks operational details like prerequisites, version checking behavior, and error handling, which are more critical given the absence of annotations and output 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?

The description adds no information about any of the four parameters. The schema covers only 50% of parameters with descriptions, and the important 'expected_version' parameter is left unexplained in both schema and description, so the description 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?

The description clearly identifies the action ('mark... as completed'), the resource (task), and the eligible states (claimed/in-progress/revision-requested). This distinguishes it from sibling tools like approve_task and request_revision, which involve different workflow steps.

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

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

The description implies when to use the tool by specifying the task states it applies to, giving the agent context on eligibility. However, it does not explicitly mention when not to use it or point to alternatives, though the sibling list provides that context.

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 burden of behavioral disclosure. It adds one useful behavior: tasks 'start in status pending'. It also implies a workflow where implementers pick up tasks. However, it doesn't mention whether permissions are needed, whether the task is immediately visible, or what the response is. This is minimal but acceptable for a straightforward creation tool.

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

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

Two sentences with no filler. The first sentence front-loads the core action and target, the second adds a key state detail. Every word 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?

Given the tool has 10 parameters and no output schema, the description is reasonably complete for a creation operation. It sets the task status and the intended actor, which addresses workflow context. It doesn't explain return values, but that is often implicit for create actions. A bit more detail on how creation fits the overall task lifecycle (e.g., 'assignee' pre-claiming) would make it fully complete, but it's above minimum viable.

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

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

The input schema covers 100% of parameters, so the baseline is 3. The description adds no parameter-specific details—it doesn't elaborate on 'assignee', 'priority', or 'expected_output'. The phrase 'for an implementer to pick up' hints at assignee/claiming but not explicitly. Satisfies the baseline without exceeding it.

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

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

The description clearly states the verb and resource: 'Create a new coordination task'. It also specifies the target audience ('for an implementer (e.g. OpenCode) to pick up') and initial status, which differentiates this creation tool from sibling tools like list_tasks or claim_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 description provides clear context: use this tool to create tasks for implementers to pick up. Though it doesn't explicitly mention alternatives, the purpose is unmistakable compared to siblings. It lacks an explicit 'when not to use' but that is not critical for a creation tool with obvious intent.

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

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

With no annotations, the description carries the transparency burden. "Fetch" implies a read-only operation, and the optional timestamp filter discloses a behavior. However, it does not describe return format, ordering, pagination, or whether messages are marked as read, leaving notable gaps for a fetch tool.

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

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

The description is a single, front-loaded sentence with no filler. It states the core function and an optional parameter in a concise manner, scoring highly on efficiency.

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 only two parameters and no output schema, the description covers the main purpose and optionality. However, it omits expected return structure, potential errors, or any preconditions (e.g., task must exist), making it minimally complete but with clear 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 50%, and the description does not fully compensate. For 'since', the description merely repeats the schema's description. For 'taskId', it provides context by linking it to a task's thread, but the meaning of the parameters is still largely left to the schema. The description adds some clarity but not enough to fully cover the gap.

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

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

The description uses a specific verb "Fetch" and a clear resource "a task's conversation thread," which distinguishes it from sibling tools like post_message (write) and get_task (task details). The optional timestamp filter is also mentioned, providing a clear scope.

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

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

The description implies the tool is used to retrieve message threads for a task and mentions an optional filter, but it does not explicitly state when to use this over alternatives or any exclusions. No alternatives are named, and there is no guidance on when not to use it.

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

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

With no annotations, the description carries the burden, and it does add the key behavior of returning null if no progress exists. However, it doesn't disclose other potential behaviors like error responses for invalid task IDs or read-only guarantees, though 'Fetch' implies no side effects.

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

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

The description is a single, well-structured sentence with the verb front-loaded. Every word adds value, including the null-return behavior, making it concise and readable.

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

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

Given no output schema and simple parameters, the description is fairly complete: it states what is fetched and the null behavior. It doesn't specify the return structure or error handling for non-existent tasks, but for a simple fetch tool it's adequate.

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 no parameter descriptions and covers 0% of semantics, so the description must compensate. It only says 'for a task', which adds little beyond the parameter name 'taskId' and doesn't explain the format or source of the ID.

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 fetches a progress snapshot and history for a task, using a specific verb and resource. It distinguishes itself from siblings like get_task and update_progress by focusing on progress data.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of using get_task for task details or that update_progress is for modifying progress, so the description lacks explicit usage context.

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. It discloses the read-only nature via 'fetch' and lists included content (status, version, history), but it does not mention error handling, return format details, or any prerequisites. For a simple read operation this is a moderate 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?

The description is a single, front-loaded sentence that states the verb, object, qualifier, and key content. Every word contributes value with no redundancy.

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

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

For a simple one-parameter read tool with no output schema, the description adequately conveys what is returned (full details, status, version, history) and the input required. It could mention error behavior or edge cases, but these are minor gaps for this tool's simplicity.

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

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

Schema description coverage is 100%, and the single 'id' parameter is fully documented in the schema with a pattern and example. The description adds no extra parameter meaning beyond reinforcing 'by id', 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 clearly states the tool fetches full details for a single task by id, with a specific verb ('fetch') and resource ('task'), and uniquely identifies the scope ('by id') distinguishing it from siblings like list_tasks and search_tasks.

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

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

Clear context is given: use when you need full details for one task by its id. No explicit exclusions or alternatives are named, but the 'by id' qualifier makes the appropriate usage obvious relative to sibling tools that list or search 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 burden of behavioral disclosure. It discloses that the output is a lightweight summary with no history[] and includes a computed idleSeconds while claimed/in_progress, and notes the cost benefit for polling. It does not explicitly state whether filters are combined with AND/OR, pagination, or ordering, but as a 'list' operation it clearly implies read-only behavior.

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

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

The description is two sentences with no waste. The first sentence states the action and filters, the second provides important behavioral detail (lightweight summary, no history, idleSeconds) and points to get_task. Every clause contributes to understanding the tool.

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 list tool with 4 optional parameters and no output schema, the description gives useful context about return content and the trade-off vs get_task. However, it omits details about pagination, ordering, or result limits, which could matter in repeated polling. The presence of search_tasks as an alternative is not addressed, leaving some contextual 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%, and the description only lists the filter names (status, assignee, creator, tag) without adding meaning. It does not explain the expected format for assignee/creator, whether tag is exact/substring, or how multiple filters interact. The status enum is provided in the schema, but the description adds no parameter-level value.

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's function: 'List coordination tasks' with optional filters by status, assignee, creator, or tag. It distinguishes itself from the sibling get_task by explicitly noting that this tool returns a lightweight summary and directing users to get_task for full records. This is a specific verb+resource+scope statement.

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 this tool: repeated polling stays cheap, and for full records including history, call get_task. It names get_task as the alternative. However, it does not mention search_tasks, another sibling, leaving ambiguity about when to choose list_tasks vs search_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 must disclose behavioral traits on its own. It only states the action without mentioning side effects, required permissions, rate limits, failure behavior, or whether the message is appended. For a mutating tool, this is a significant gap.

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

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

The description is a single, well-structured sentence that includes practical examples without any redundancy. It is appropriately sized and front-loaded with the action.

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 with three self-explanatory parameters and no output schema, but the description lacks details about prerequisites (e.g., task must exist) and failure modes. It is adequate for a basic tool but has clear gaps given there are no annotations to provide safety/reversibility 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 0% description coverage, so the description must compensate. It implies the role of taskId and content via 'task's conversation thread' and examples, but it does not explicitly explain the author parameter or any additional constraints. The parameter names are self-explanatory, offering partial compensation.

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's purpose with a specific verb ('post') and resource ('message to a task's conversation thread'), and the examples clarify the intended content types. It is distinct from sibling tools like get_messages, which is the read counterpart.

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 usage context through examples (clarifications, review feedback, status notes), implying when to use this tool. However, it does not explicitly mention alternatives or exclusions, such as 'for reading messages, use get_messages', so it falls short of a 5.

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

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

With no annotations, the description carries the burden of explaining side effects. It explicitly discloses that the operation 'clears assignee and prior progress', which is critical and potentially destructive. It also notes the return value is a task summary without history. The description is transparent about these behaviors, though it does not discuss permissions or failure conditions.

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, front-loaded with the primary action, and every sentence adds value. It states the purpose, the side effects, and the return behavior without wasted words. The structure is clear and easy to parse.

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

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

The description covers the core purpose, side effects, and return value, but with four parameters and no output schema, it leaves significant gaps. It does not explain the meaning of 'by', 'reason', or 'expected_version', and does not mention potential error cases or prerequisites. The description is useful but not fully complete for a tool of this complexity.

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

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

Schema description coverage is 0%, and the description does not explain any of the four parameters (id, by, reason, expected_version). It does not mention that 'reason' is likely optional or that 'expected_version' is for optimistic locking. The description adds no meaning beyond the raw schema, leaving the agent without guidance on how to fill these fields correctly.

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's action: 'Reopen a cancelled/completed/approved task back to pending'. It uses a specific verb ('reopen') and identifies the resource ('task') and the state transition, distinguishing it from sibling tools like cancel_task or approve_task. The scope is explicit.

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 this tool: when a task needs to be reopened for re-claiming. It also contrasts with get_task by noting that history[] is not included, directing users to get_task if they need that. However, it does not explicitly state when not to use it or mention alternative tools for similar state changes.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It does disclose that feedback is posted as a message and that the return value lacks history. However, it does not explicitly state whether the task status changes, permissions required, or other side effects, leaving noticeable gaps.

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, front-loaded with the primary action, and contains no redundant phrasing. Every clause adds value (action, side effect, return value limitation).

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 core purpose, side effect, and return value, and points to get_task for history. However, it omits explanations for key parameters (id, by, expected_version) and does not state the resulting task status or prerequisites beyond 'completed task'. Given no output schema and sparse annotations, this is adequate but incomplete.

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

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

Schema description coverage is only 25% (only feedback has a description). The description adds some meaning for feedback (posted to thread) but does not explain id, by, or expected_version. With such low coverage, the description should compensate more but does not.

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's function: send a completed task back for changes and post feedback to the task's thread. It distinguishes from sibling tools like complete_task or approve_task by focusing on revision, and explicitly contrasts with get_task by noting the return value lacks history.

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 it: when a completed task needs changes. It also provides a routing hint to use get_task for history, which helps the agent choose between tools. However, it does not explicitly mention when not to use it or list alternatives, so it falls short of a 5.

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

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

With no annotations provided, the description takes on full responsibility. It discloses key behavioral traits: case-insensitive substring match across specific fields, the lightweight summary return shape, and the absence of history[]. It also indicates a read-only operation implicitly. This is helpful but does not cover potential pagination or ordering behavior.

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

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

The description is concise at two sentences, front-loaded with the core function, and adds crucial details about the return shape and follow-up tool. Every word earns its place 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?

Given the tool's simplicity (one parameter, no output schema), the description adequately explains what it does and what it returns. It references list_tasks for the summary shape and get_task for full data. It could mention result limits or ordering, but these are not critical for a basic search. Overall, it is a complete and useful description.

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 only defines 'query' as a string with a minimum length, providing no description. The description fully compensates by explaining that the query is matched against task titles, descriptions, and tags, and that matching is case-insensitive substring-based. This adds substantial meaning beyond the bare schema.

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

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

The description clearly states it performs full-text search over task titles, descriptions, and tags with a case-insensitive substring match. It also distinguishes itself from list_tasks by clarifying the return shape (same lightweight summary, no history[]) and directly points to get_task for full records.

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: use this for searching by text, and call get_task for full detailed records. It implicitly differentiates from list_tasks by focusing on search over listing. However, it does not explicitly state when NOT to use it or name alternatives beyond get_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?

No annotations are provided, so the description carries full burden. It discloses the automatic status advancement to in_progress, rejection of invalid task states, and the return value lacking history. This gives the agent insight into side effects and boundaries beyond basic read/write hints.

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 concise sentences pack purpose, constraints, side effects, and redirects. No fluff, front-loaded with the primary action, and every sentence earns its place.

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

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

While the core behavior is well covered, the absence of parameter explanations and any output structure means the description is incomplete for a 6-parameter tool. It covers 'what' and 'when' but not the full 'how', leaving significant gaps for the agent.

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

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

Schema coverage is 0%, so the description must compensate. It explains percent's range and type (0-100 whole numbers), but taskId, by, notes, current_step, and expected_version are unexplained. This leaves the agent guessing about required identifiers and optional context fields.

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 ('Report progress') and resource (task), with scoping constraints (0-100, whole numbers). It also distinguishes from siblings by noting the returned snapshot lacks history (call get_progress for that), clearly separating it from tools like complete_task and claim_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?

It explicitly states acceptable task statuses ('claimed/in-progress/revision-requested') and that other states (pending, completed, approved, cancelled) are rejected. It also directs users to get_progress for history, providing an explicit alternative for a related need.

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 full burden. It discloses key behaviors: lock-free polling, the change-detection semantics, and that timing out is normal. However, it doesn't specify what happens for an invalid/nonexistent task id or whether any state is modified, leaving a small transparency gap.

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

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

Three dense sentences, each earning its place: main action, behavioral modes, and timeout handling. Front-loaded with the key purpose, no wasted words.

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?

While the description covers the main behavior, the absence of an output schema means the return structure remains vague—only 'timed_out: true' is mentioned, not what is returned on a status change. Error handling for non-existent tasks is also unaddressed. Overall good but not fully complete for a tool with no 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 67%, and the description adds important semantics beyond the schema: the meaning of omitting versus providing until_status, and the timeout behavior ('timed_out: true' is normal). The id parameter has only a pattern, and the description doesn't elaborate on it, but the schema's enum and description for until_status are reinforced.

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

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

The description states a specific action: 'Block (polling, lock-free) until a task's status changes, or until timeout_seconds elapses' and explicitly distinguishes from sibling get_task by saying 'use instead of repeatedly calling get_task in a loop.' This clearly identifies the tool's unique role.

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 direction on when to use: 'use instead of repeatedly calling get_task in a loop.' Also explains the two modes (with/without until_status) and the expected behavior on timeout ('re-call to keep waiting'), providing clear operational guidance.

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