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

With no annotations, the description carries the full burden, and it does contribute two real behavioral facts: failure semantics ('Returns an error if unavailable') and an auth prerequisite ('Requires write role'). It still omits whether the claim is reversible/releasable, what the returned error or success looks like, and whether it mutates persistent 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?

Three short sentences, zero filler, and the core action is front-loaded ahead of the failure and permission caveats. Every sentence carries information.

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

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

For a mutation tool with no annotations, no output schema, and two undocumented parameters, the description covers the essentials of failure and permission but leaves the return value, state effects, and parameter meaning unaddressed. Adequate 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?

Both parameters have 0% schema description coverage, so the description is the only place semantics could be added, yet it never mentions 'id' or 'agent_id'. The names are largely self-explanatory, which softens the gap, but the description does not compensate for the coverage hole.

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/lock') and resource ('todo task') with the acting party ('for an agent'), so the operation is unambiguous. It does not, however, position itself against siblings like boardagent_complete_task or boardagent_update_task, so an agent must infer the boundary itself.

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 word 'todo' implies usage (claim only tasks in a todo state), but there is no explicit when-to-use/when-not statement and no named alternative for the adjacent operations (complete, update, create). Usage is implied rather than directed.

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 the authorization model (owning agent only, write role required), but says nothing about the resulting task state, whether completion is reversible, or error behavior on permission failure.

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

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

Three short sentences, action first, prerequisites after. No filler and nothing redundant.

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

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

For a mutation tool with no annotations, no output schema, and two undocumented parameters, the description covers authorization but omits state-change semantics and parameter meaning. It is minimally adequate but leaves gaps an agent must guess at.

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% — neither 'id' nor 'agent_id' has any description. The description does not identify what 'id' refers to or whose 'agent_id' is expected (the caller's or the owner's), 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?

States a specific verb+resource ('Mark a task done') that is clearly distinct from siblings like claim_task, update_task, and delete_task. It does not explicitly contrast with claim_task, but the action is unambiguous.

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

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

Gives concrete preconditions: only the owning agent may complete it and a write role is required. It states when the call will succeed but does not name alternatives for non-owning agents (e.g., claim or update instead).

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

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

With no annotations at all, the description carries the full burden and does disclose two non-obvious traits: the forced initial status ('always created as todo') and the authorization requirement ('Requires write role'). It still omits return behavior, error/duplicate handling, and whether the new task id is returned.

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

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

Three short sentences, front-loaded with the core action and free of filler. The enumerated color list partially duplicates the schema enum, which is the only mild 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 14-parameter mutation tool with no annotations and no output schema, the description covers auth and initial state but says nothing about the returned value, defaults beyond priority, or what most parameters do. Adequate but with visible gaps 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 71% across 14 parameters, so the schema documents most fields itself. The description clarifies that priority is expressed as a color, but that largely restates the enum already present in the schema and adds no meaning for due, estimate, dependencies, custom_fields, or metadata.

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 ('Create a new task'), which cleanly separates it from the list/get/update/delete/claim/complete siblings without needing to name them. It never explicitly contrasts against those siblings, 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?

The clause 'Tasks are always created as todo (claim to start work)' implies a create-then-claim workflow, which is useful routing guidance. However, no alternative tool is named and there is no explicit when/when-not condition, so the guidance is only implied.

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 admin-role requirement, which is valuable, but does not state whether deletion is permanent, cascading, reversible, or what the result looks like for a destructive operation.

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

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

Two short sentences, zero waste, and the core action is front-loaded before the permission caveat. Perfectly sized for the tool's complexity.

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 a single parameter, no output schema, and no annotations, the description covers the basic purpose and auth requirement. However, for a destructive delete operation it omits important context about permanence and 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?

There is one parameter, id, and schema description coverage is 0%. The description says 'by id' but adds no format or type detail beyond the schema's integer declaration. For a single obvious identifier, this is minimally acceptable.

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 (Delete), a specific resource (task), and the key identifier (by id). This clearly distinguishes the tool from all siblings such as create_task, update_task, claim_task, and complete_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 notes the prerequisite of admin role, which is useful context, but does not say when to use this tool versus alternatives like update_task or complete_task. Usage is implied by the tool name rather than explained.

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 that the operation is a read and requires read role, which is useful authorization context, but it does not describe return behavior, missing-record handling, or any other operational traits.

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, front-loaded sentences with no wasted words. The core action is stated first, followed by the role requirement, which is an efficient structure.

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

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

For a simple single-parameter read tool, the description covers the essential action and permission requirement, but it omits return-value expectations and edge-case behavior. It is minimally adequate but not fully complete.

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

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

Schema description coverage is 0% and the single parameter has no schema description. The description only repeats 'by id' without clarifying what the id identifies or its expected format, adding virtually no meaning beyond the schema's id integer property.

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: read a single task by id. It clearly distinguishes itself from list tools by specifying 'single' and 'by id', though it does not explicitly name any sibling alternative.

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

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

The only usage guidance is 'Requires read role', which states a prerequisite but not when to use this tool versus alternatives like boardagent_list_tasks. There is no explicit when-to-use or when-not-to-use guidance.

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

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

No annotations provided, so description carries full burden. It discloses a read-role requirement, which is useful, but omits return format, pagination behavior, and whether results are sorted or truncated. Minimal behavioral context.

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

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

Two short sentences, front-loaded with purpose. However, it is under-specified for a tool with five parameters, making conciseness come at the cost of needed detail.

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

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

Inadequate for a list tool with five parameters, no output schema, and no annotations. Missing filter semantics, return shape, and pagination behavior, which an agent needs to invoke it correctly.

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

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

Schema coverage is 40% (only limit and offset described). The description adds no parameter details beyond 'optionally filtered', leaving owner, status, and project undocumented. Fails to compensate for low schema coverage.

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

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

States a clear verb 'List' and resource 'tasks', and the plural distinguishes it from the sibling 'boardagent_get_task' which likely retrieves a single task. No explicit sibling differentiation in text, but the intent 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?

Only mentions 'optionally filtered' and 'Requires read role'. No guidance on when to use this vs get_task, or when to prefer this over claim/complete. No exclusions or alternatives named.

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

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

With no annotations, the description carries the full burden, and it does add two genuine behavioral facts: metadata is merged into agent_id's namespace, and a write role is required. It still omits whether omitted fields are preserved or cleared (partial vs full replacement), validation/failure behavior, and reversibility, which matters for a mutation tool.

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

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

Three short sentences, front-loaded with the action, and no filler. The brevity is efficient, though it edges into under-specification for a 16-parameter mutation 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?

Given 16 parameters, 0% schema coverage, no annotations, no output schema, and nested objects, this description is far too thin. It covers the core purpose and two behavioral facts but leaves the agent without guidance on the vast majority of 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 16 parameters, so the description must compensate and largely does not. It clarifies only the metadata/agent_id relationship; the status and priority enums, due format, dependencies, custom_fields, and the remaining parameters get no semantic explanation.

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 ('Update a task'), which is enough to distinguish it from the create/list/get/delete/claim/complete siblings by verb. However, it never says which aspects of the task are updatable, leaving the scope of the operation thin relative to a 16-parameter 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?

The only guidance is 'Requires write role,' which is a prerequisite rather than usage context. There is no statement of when to use this tool versus boardagent_claim_task, boardagent_complete_task, or boardagent_create_task, and no exclusions or conditions.

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