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 additive semantics (existing assignees preserved) and that the task is returned, but omits permission/auth requirements, duplicate handling, and behavior on an unknown member name or id.

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

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

One sentence, front-loaded with the action and target, with no filler. Every clause (multi-member, name-or-id, additive, returns task) earns its place.

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

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

For a simple two-parameter mutation with no annotations and no output schema, the description covers the core semantics and return value but leaves error/permission behavior and input validation details unspecified.

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 contributes no parameter descriptions. The description adds real value by stating assignees accept 'name or id' and that the target is a task, but it does not clarify that the bare 'id' parameter is the task id nor mention the minItems/maxItems bounds.

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 (assign), the resource (workspace members), the target (a WEEEK task), and the additive scope ('keeping the existing assignees'). This clearly separates it from the sibling weeek_remove_assignees and from any replace-style operation.

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 'keeping the existing assignees' implies when this tool is appropriate versus a replacement operation, and the sibling weeek_remove_assignees is the obvious inverse. However, there is no explicit when-to-use/when-not-to-use statement or named alternative.

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 supplied, so the description carries the full burden. It usefully discloses that the comment is authored as the token's owner (no impersonation) and that content is markdown. It omits permission requirements, error behavior, and whether the resulting comment can be edited, which matters for a mutation tool with zero annotation coverage.

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

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

Two sentences, both front-loaded with the essential action first and the threading caveat second. Nothing is redundant or padded.

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?

No output schema and no annotations exist, so the description has to do more work than it does. It covers purpose, threading, and identity but never states whether the new comment id is returned, what auth scope is needed, or what failure modes look like.

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 fully documents `reply_to` (comment id from weeek_list_comments) and clarifyes `markdown` as the body format, but `id` is only inferable from the phrase 'to a WEEEK task' and the minLength=1 constraint is never surfaced.

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 ('Add a markdown comment to a WEEEK task') and immediately scopes it with the identity constraint ('as the token's owner'). Clearly distinguishable from the comment siblings weeek_list_comments and weeek_delete_comment.

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

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

Gives an explicit conditional for the reply flow: pass `reply_to` to answer in a thread, and it names weeek_list_comments as the source of valid ids. It doesn't cover when not to use it (e.g., editing an existing comment) or any permissions prerequisites, so it stops short of the 5 level.

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, yet it omits permissions/authorization needs, whether the operation is idempotent (what happens on re-adding), what occurs when column is omitted, and what the response looks like. It does disclose one useful trait – that a task can belong to multiple projects – but that is thin for a mutation tool with zero annotation coverage.

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

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

Three short sentences with no filler; the core behavior and the sibling disambiguation are front-loaded, and every sentence adds 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 0% parameter description coverage, the description adequately covers purpose, routing, and parameter format, but leaves behavioral gaps (permissions, idempotency, column default, result shape) that an agent would need in order to call it confidently.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that project and column accept a name or an id and that column is optional, which adds real meaning beyond the schema types (string|number), but it says nothing about the required id parameter or about default column placement when omitted.

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 action on a specific resource (showing an existing WEEEK task in another project) and the parenthetical '(a task can live in several)' pins down the semantics as multi-project membership rather than a copy. It also names the sibling it is not (weeek_move_task), so an agent can distinguish it without opening 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?

Provides a clear use condition (task should appear in an additional project) and an explicit alternative with the selecting condition: use weeek_move_task to move between boards of one project. It does not mention the natural inverse sibling weeek_remove_task_from_project, so it stops short of full alternative coverage.

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 return value ('Returns the task; watchers are its `watchers` field'), which matters since there is no output schema, but says nothing about permissions, idempotency, duplicate handling, or what happens when a name cannot be resolved.

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 filler, with the operation and its purpose front-loaded before the return-value note.

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

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

Given no annotations, no output schema, and 0% schema coverage, the description covers the essentials (what a watcher is, accepted identifier forms, return shape) but leaves gaps around the task `id` parameter, error behavior on unresolvable members, and permission requirements.

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 does add meaning for the `watchers` parameter by stating members may be given 'by name or id', which explains the string|number union, but the `id` parameter (implicitly the task id) is never explained, nor is the 50-item cap.

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 ('Add members ... as watchers of a WEEEK task') and clarifies the effect ('so they get its notifications'), which distinguishes watchers from assignees. It never names a sibling tool explicitly, but the operation 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?

Usage is only implied by the purpose statement; there is no explicit when-to-use guidance, no note on when this is preferable to weeek_add_assignees, and no exclusion or precondition (e.g. task must exist, member must belong to the workspace).

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?

The description transparently discloses the tool's safety boundary (allowed directory and refusal for outside paths) and the configurable directory via WEEEK_ATTACH_DIR. This goes beyond the openWorldHint annotation, which only signals external interaction, providing concrete behavioral guidance for error prevention.

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-loads the primary purpose, and immediately follows with a critical safety note. No redundant words or filler. Perfectly sized for quick parsing.

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 2-parameter tool with openWorldHint and no output schema, the description provides sufficient context: purpose and the key security restriction. It omits return behavior or effects on existing attachments, but these are less critical for a straightforward attach operation.

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 0% schema coverage, the description adds meaning for 'path' by detailing the allowed directory constraint, but it does not explicitly clarify path format (absolute vs relative) or elaborate on task_id beyond the task context. Partial compensation for the schema gap.

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

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

The description states a specific verb ('attach'), an object ('local file'), and a target ('WEEEK task'), clearly distinguishing it from all sibling tools. It is unambiguous and immediately understandable.

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

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

The description gives clear context for when to use the tool (attaching a local file to a task) and adds a crucial constraint (only files within the allowed directory). It does not explicitly name alternatives, but no sibling tool serves this purpose, so clear context without exclusions is sufficient.

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 disclosure burden. It accurately conveys the core behavior (completing or reopening) and adds the nuance that setting completed to false reopens the task. However, it does not disclose any potential side effects, permissions, or error handling, which leaves some ambiguity for a mutation tool.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and key parameter usage. No redundant words or unnecessary details.

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

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

For a simple toggle tool, the description covers the essential behavior. However, with no annotations and no output schema, it does not mention what the tool returns (if anything) or any prerequisite conditions, which could leave the agent unaware of expected responses or failure modes.

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 the completed parameter's meaning via 'completed:false', but it does not explicitly clarify that 'id' refers to the task ID or that completed maps directly to the boolean field. The description adds minimal value beyond the schema's property names.

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 with a specific verb ('Mark') and resource ('WEEEK task complete'), and also mentions the ability to reopen (completed:false). This distinguishes it from sibling tools like update_task, which would be for changing other task fields.

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 set a task's completion status. It does not explicitly exclude alternatives or mention update_task, but the specificity of 'complete or reopen' makes the intended usage obvious.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses that names or ids are accepted and that omitting assignee self-assigns, but says nothing about permissions/auth, whether the assignee is notified, or what the call returns — the latter matters because `parent` requires a task id. Adequate but with real 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?

Purpose is front-loaded in the first four words, followed by a compact enumeration of inputs and two short routing sentences. It is dense but each clause carries information; the list style is slightly long but nothing is 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 10-parameter creation tool with a nested `fields` object, no output schema, and no annotations, the description covers the parameters and the id-lookup convenience well. It omits the return value and any side effects, but the coverage is otherwise sufficient for correct invocation.

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

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

With schema description coverage at only 20%, the description compensates well: it explains that project/column/assignee accept a name or id, that `due` is natural language, that `parent` makes the task a subtask, and that `fields` takes custom-field values keyed by field name (global and project fields). Only minor gaps remain (e.g. `description` and default column behavior).

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

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

Opens with a specific verb+resource ('Create a WEEEK task') and then enumerates the accepted inputs, which lets an agent distinguish it from weeek_update_task, weeek_create_tasks (bulk), and the assignee-management siblings. The mention of weeek_add_assignees / weeek_remove_assignees further draws the boundary against sibling tools.

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

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

Gives concrete operational guidance: 'One call — no need to look up ids first,' 'Omit `assignee` to self-assign,' and routes later assignee changes to weeek_add_assignees / weeek_remove_assignees. It stops short of explicit when-not-to-use conditions (e.g. bulk creation vs weeek_create_tasks), so it is clear context without full 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 substantial work: creation order, non-atomic failure semantics ("one bad name does not abort the batch"), and the exact per-item reply shape including the error/candidates variant. It omits permissions and rate-limit context, so it is strong but not exhaustive.

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, no filler: batch capability first, then field contract, then failure/return behavior. 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?

There is no output schema, and the description steps in by describing the per-item response contract (`{ ok: true, task }` / `{ ok: false, error, candidates? }`), which is exactly what an agent needs to parse results. Auth requirements and any batch size/rate constraints are the remaining gap.

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?

Top-level schema description coverage is 0%, so the description must compensate, and it does: it names the required fields (`title`, `project`, with name-or-id accepted) and enumerates all optional ones. It adds meaning beyond the schema, though it does not explain value formats for fields like `due` or `column` beyond what nested schema text provides.

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

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

States a specific verb (create), resource (WEEEK tasks) and scope (up to 50 in one call), which cleanly separates it from the single-item sibling weeek_create_task. An agent can tell exactly what this does 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?

The batch framing ("up to 50 ... in one call") makes the intended usage clear and implicitly routes single-task creation to weeek_create_task, which it names. It stops short of an explicit when-to-use/when-not rule, so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds meaningful context beyond that: the deletion is 'permanent'/'irreversible' and gated behind an explicit confirm:true flag, which reinforces the destructive semantics without contradicting them.

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 with no filler. The destructive consequence and the confirm gate are front-loaded where the agent will see them first.

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, 3-parameter destructive operation with annotations covering destructiveness and no output schema to explain, the description supplies everything critical: what is deleted, that it is irreversible, and the confirmation requirement. Only the exact meaning of each ID parameter is left implicit.

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 only 33% – only 'confirm' is documented in the schema. The description compensates partially by implying the two integer IDs map to a task ('from a WEEEK task') and a single comment, and repeats the confirm requirement, but never clarifies id vs comment_id explicitly.

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 ('delete') on a specific resource ('one comment from a WEEEK task'), with the permanence qualifier. An agent can instantly distinguish this from weeek_delete_task and the comment siblings (weeek_add_comment, weeek_list_comments).

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 conveys the context (removing a single comment) and states the confirm:true prerequisite, but never says when to prefer this over alternatives or what happens if the comment or task doesn't exist. Usage is implied rather than guided.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the bar is lower, yet the description still adds real value: it clarifies the operation is irreversible and distinct from completion ('removed, not just completed') and that a confirmation flag is mandatory. It stops short of covering permissions, failure modes for a bad id, or cascading effects on subtasks/comments.

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-loaded with the destructive action, then the guard condition, then the alternative. Every clause earns its place with zero 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 two-parameter delete tool with no output schema, the description covers purpose, irreversibility, confirmation, and the sibling alternative. Only minor gaps remain, such as behavior when the id does not exist or permission requirements.

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%: confirm is self-documenting via its const/description, while id has no schema description. The description only implies id semantics via 'by id' and does not add format or validation detail. Baseline 3 is appropriate given the schema carries the confirm constraint.

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?

Specific verb (permanently delete) and resource (a WEEEK task), plus the scoping qualifier 'by id'. It explicitly contrasts itself with the nearest sibling, weeek_complete_task, so an agent can disambiguate without reading either schema.

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

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

States the precondition ('Requires confirm:true') and names the alternative tool with the condition that selects it ('to merely close a task use weeek_complete_task instead'). This is exactly when-to-use / 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: the return type is conditional – hosted images come back as the image itself, everything else as metadata. It omits auth needs, error/failure behavior, and size limits, so it is good but not exhaustive.

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-loads the core action, then adds the image-reading rationale and id provenance. Slightly narrative but every clause carries 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?

No output schema or annotations exist, so the description must cover returns and it does explain the two return shapes. The remaining gap is the undocumented `metadataOnly` flag, which an agent would need to know to force metadata-only responses.

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 adds real meaning for `id` (provenance from the task attachments list) but never mentions the `metadataOnly` boolean, leaving one of two parameters completely 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?

States a specific verb and resource ('Read one WEEEK attachment by id') and is immediately distinguishable from the upload sibling weeek_attach_file. An agent can tell what it retrieves 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?

It explains where ids come from (a task's `attachments` list via weeek_get_task) and gives a concrete motivating scenario for reading images rather than guessing from text. There is no explicit when-not or exclusion, but the routing context is clear.

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

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

No annotations exist, so the description carries the full burden, and it does disclose that this is a read that returns a rich payload (assignees, watchers, subtasks, time entries, custom fields). It remains silent on error behavior for missing ids, permissions, and rate limits, so the disclosure is partial.

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

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

A single front-loaded sentence led by the verb and resource, followed by the returned-field list. The field list is long but justified given there is no output schema, and no sentence is 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?

With no output schema, the enumeration of returned fields (including nested parent/subtasks and resolved custom-field option names) is exactly the detail an agent needs to plan around the response. Only failure/permission behavior is absent, which is a modest gap for a single-param read.

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 single 'id' parameter is undocumented in the schema; the description only adds that it identifies one task ('by id' / 'task by id'). That is the minimum needed but no format, type, or source-of-id guidance is given.

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 ('Get one WEEEK task by id') and the 'one ... by id' framing inherently distinguishes it from the sibling weeek_list_tasks and weeek_get_attachment. An agent can identify the tool's function 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?

'By id' implies the caller must already know a task identifier, which is the implied usage condition. However, it names no alternative (e.g., use weeek_list_tasks to find an id first) and gives no 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?

With no annotations, the description must carry the full burden. 'List' implies a safe read, and it discloses the returned fields (id, name, privacy), which is useful. However, it says nothing about pagination, empty results, auth requirements, or rate limits, leaving 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?

Two short sentences, front-loaded with the resource and scope, then the routing hint. No filler text.

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?

No output schema exists, so it is good that the description names the returned fields. Combined with the single-parameter schema and the downstream-tool hint, the definition is nearly complete, lacking only pagination and error behavior detail.

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 single parameter is undocumented in the schema. The description compensates by explaining that 'project' accepts a name or id, which maps the string|number union to meaningful semantics.

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 ('List the boards of a WEEEK project') and even enumerates the returned fields (id, name, privacy). It differentiates implicitly by naming the downstream tools it feeds, though it does not directly contrast with siblings like weeek_list_projects or weeek_list_columns.

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

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

Explicitly tells the agent the purpose context: 'Use it to find a board for weeek_move_task or weeek_list_columns.' This is clear when-to-use guidance with named alternatives, but there is no when-not or prerequisite information (e.g., permissions).

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

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

No annotations are provided, so the description carries the full burden. "List" implies a read-only operation and the return fields are disclosed, but nothing is said about permissions, whether the lookup by name is case-sensitive, or what happens if the board/project pair does not resolve.

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, purpose front-loaded, then the invocation rule. No filler and nothing repeated from the schema.

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 two-parameter, read-only list tool with no output schema and no annotations, the description covers purpose, lookup semantics, and return shape. Only minor gaps remain (auth/scope behavior, behavior on unresolved board names), and no output schema is present to offload return-value documentation.

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 raw schema (two string|number properties named board and project) is nearly opaque. The description compensates by explaining the id-vs-(name + project) lookup relationship, which is the key semantic an agent needs. It remains slightly ambiguous whether `project` is an id or a name, keeping it out of 5 territory.

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 ("List the columns of a WEEEK board") and even enumerates the returned fields (id, name, boardId). No sibling tool lists columns, so an agent can immediately distinguish it from weeek_list_boards, weeek_list_projects, or weeek_list_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?

The second sentence gives invocation guidance (pass board by id, or by name together with its project), which is useful, but it describes *how* to call rather than *when* to choose this tool over alternatives. No exclusions, prerequisites, or when-not conditions are 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 exist, so the description carries the full burden. It adds genuine behavioral context the schema cannot express (result fields, pagination and the `hasMore` continuation signal), but it omits permission/auth requirements, behavior on an invalid or empty task id, and how `limit` caps at 50.

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-loaded with the operation and resource, followed by the paging rule. 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?

With no output schema, disclosing the returned fields (id, author member id, markdown, reply parent, timestamps) and the pagination contract covers most of what an agent needs. Missing only parameter bounds and failure 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 `offset` implicitly via the paging advice and clarifies the shape of the returned comment, but leaves `limit` (default 20, max 50) and the exact meaning of `id` (task id, not comment id) unaddressed.

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 scoped to a task ('List the comments on a WEEEK task') and enumerates the returned fields, making it unmistakable next to siblings like weeek_add_comment, weeek_delete_comment, and weeek_get_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?

Usage context is only implied: you call this to read a task's comments. The description does say how to continue paging ('call again with a larger offset', `hasMore`), which is useful, but it names no alternatives and states no preconditions such as needing a valid task id.

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

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

With no annotations, the description carries the full disclosure burden, and for a zero-parameter read it does disclose the shape of what comes back (id + display name) and how the output is consumed elsewhere. It says nothing about scope limits, permissions, or whether the list is paginated/filtered.

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: the first defines the operation and its return, the second delivers the integration guidance. No filler, and the core purpose is front-loaded.

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

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

There is no output schema, so describing the returned fields and their downstream use is exactly the missing piece this description supplies. For a simple, parameterless listing tool, nothing further is needed 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?

The tool takes no parameters, so there is nothing to disambiguate; the baseline for a 0-param tool is 4. The description correctly does not waste space explaining inputs.

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 (list WEEEK workspace members) and even names the returned fields (id + display name). This cleanly separates it from sibling list operations like weeek_list_projects, weeek_list_boards, and weeek_list_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?

Gives a clear reason to call it ('use this to see who exists') and explains the downstream payoff: names returned here can be passed directly into any assignee/watcher/member tool. It does not name a competing alternative or state exclusions, so it falls just short of a 5.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the returned field set, which substitutes for the missing output schema, but says nothing about pagination, result limits, ordering, or whether all projects or a scoped subset is returned. Adequate but with real 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?

Two tight sentences: the field list is front-loaded and the sibling routing follows immediately. Every sentence earns its place, and the enumerated fields compensate for the absent output schema rather than wasting space.

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

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

For a zero-parameter, no-annotation, no-output-schema list tool, the description covers the essential return shape and the alternative tool. It stops short of stating scope or pagination behavior, but nothing an agent needs to invoke it is missing.

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

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

The schema declares zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. No parameter-level noise or misleading hints are introduced.

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 ('List WEEEK projects') and enumerates exactly what each entry contains (id, name, isPrivate, status, portfolioId). It also explicitly differentiates itself from the sibling weeek_get_project, so an agent can choose correctly without opening either schema.

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

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

Explicitly routes the agent: use weeek_get_project when a project's description and team are needed. That gives a clear alternative and the condition selecting it, though there is no explicit when-not-to-use or scope/pagination context for the list itself.

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

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

No annotations are provided, so the description carries the full burden. It does add genuine behavior beyond the schema — server-side (not client-side) filtering and the precise allPages scoping semantics — but says nothing about permissions, result ordering, or paging limits, leaving meaningful gaps for an 18-parameter 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 filter enumeration is front-loaded in one dense sentence followed by a targeted pagination sentence; there is little wasted text. The opening sentence is long but every clause carries a distinct filter concept.

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 large-schema list tool with no output schema and no annotations, the description covers the filter dimensions and the non-obvious allPages paging behavior, which is what an agent needs to invoke it correctly. Gaps remain around sort/limit/offset defaults and default completed/deleted inclusion.

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 only 11%, the description compensates well: it maps project, board, column, assignee/userId, completion, search, priority, type, day, and start/end and completion date ranges to readable meaning, and renders the dd.mm.yyyy date format that the schema leaves as an opaque regex. It omits limit, offset, sortBy, and 'all' semantics.

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

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

The description opens with a specific verb and resource ('List WEEEK tasks') and immediately enumerates the filter surface, so an agent knows exactly what the tool returns. It does not explicitly name a sibling (e.g., weeek_get_task for a single task), but the plural list scope 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?

It gives conditional usage guidance: 'Set allPages=true together with userId, startDate, and endDate to fetch every matching page inside the connector without returning unrelated workspace pages.' That is a clear when-to-use rule, though it offers no when-not-to-use or named alternative tools.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the column target is scoped to the given board (so cross-board column names won't resolve), but it is silent on permissions, failure behavior when the column name does not exist, and whether ordering is affected.

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 the core action and followed by the prerequisite lookup hint. 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?

Adequate for a simple 3-parameter move with no output schema, so return values need not be described. Still missing error/edge-case behavior for an unmatched column and any note on how it relates to the other task-mutation siblings.

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, and it does: it explains that column accepts a name or id (matching the string|number union) and that board_id is board-scoped and discoverable via weeek_list_boards. The task id parameter is only implied by "a WEEEK task".

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 (move), resource (task), and destination (column on a board), which is enough for an agent to distinguish it from generic mutators like weeek_update_task. It does not explicitly name the sibling it competes with, but the operation 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?

Provides a real prerequisite pointer ("Find board ids with weeek_list_boards"), which is more than implied usage. However it never says when to prefer this over weeek_update_task or weeek_complete_task, both of which can also change a task's column/status.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the danger profile is covered structurally. The description adds that the call returns the task (useful given there is no output schema) and reiterates the confirm gate already documented in the schema, but says nothing about permission requirements or what happens to tasks where the member is not assigned.

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-loading the action, then the precondition, then the return value. No filler and nothing buried.

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 3-param destructive tool with no output schema, the description covers action, precondition, and return value, which is most of what an agent needs. Minor gaps remain around the id parameter's meaning and per-item failure 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 coverage is 33%; only confirm carries a schema description. The description usefully clarifies that assignees accepts names or ids, which the schema does not state, but leaves the id parameter and the 50-item cap undocumented, so it only partially compensates for the coverage gap.

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

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

Specific verb (unassign) + resource (members) + target (WEEEK task), with the accepted identifier forms (name or id) called out. It is unambiguously the inverse of the sibling weeek_add_assignees, so an agent can route between them without opening 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 description states the precondition (confirm:true required) which gates invocation, but gives no explicit when-to-use guidance, no conditions distinguishing it from siblings, and no note about mixing name/id in one call. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds genuine context beyond them: it clarifies that only one project membership is affected and the task's other project links survive, and it reinforces the confirm requirement. This is useful behavioral detail on top of the annotations.

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 tight sentence with the operation, the scope constraint, and the precondition, in that order. No filler.

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

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

For a simple three-parameter destructive tool with no output schema, the description covers the action, the partial-destruction semantics, and the confirm gate. The only real gap is the undocumented 'id' parameter, which is minor.

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 only 33% (only 'confirm' is documented). The description partially compensates by noting the project can be given 'by name or id', but the required 'id' parameter remains unexplained in both description and schema. Marginal value over the schema.

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

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

States a specific verb (remove) and resource (task from one of its projects), and the scope note 'the task keeps its other projects' distinguishes it from both weeeek_delete_task and weeeek_add_task_to_project. An agent can tell exactly which operation this is 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?

The scenario (detaching a task from a single project while retaining membership in others) is implied by the scope note, but there is no explicit when-to-use framing and no reference to the sibling weeeek_add_task_to_project. Usage is inferable rather than guided.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation profile is known. The description adds useful facts absent from structured data — the return shape ('Returns the task') and the confirm gate — but omits failure/partial-success behavior and what happens when a listed watcher isn't actually watching.

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, with the action stated first and the hard precondition second. Every clause earns its place.

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

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

For a 3-parameter mutation with no output schema, the description covers the action, the confirm requirement, the watcher identifier flexibility, and the return value. The only remaining gap is the unexplained 'id' parameter and edge-case behavior when a watcher isn't present.

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

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

Schema coverage is only 33%, so the description must compensate. It does add real meaning for 'watchers' (accepted as a name OR an id, which the bare array-of-string|number schema does not convey) and reiterates the confirm gate, but leaves the task 'id' parameter 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 ('Stop members ... watching a WEEEK task'), which is precisely the inverse of the sibling weeek_add_watchers. An agent can pick it 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?

It discloses a hard precondition ('Requires confirm:true'), which is a real gating rule, but gives no when-to-use guidance, no exclusions (e.g. what if the member isn't watching), and never names the add/remove alternative explicitly.

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 does disclose the mutation's two outcomes (attach as subtask vs. re-parent to top level via null), which is more than a bare 'set parent' would convey. It is silent on permission requirements, error behavior for invalid/cyclic parents, and what happens to existing subtasks of the re-parented task.

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 with zero padding, front-loading the primary action and then the null-case escape hatch. Every clause earns its place.

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

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

No output schema or annotations exist, but for a two-parameter setter the description covers both the write and the detach semantics adequately. Minor gaps remain around permissions and invalid-parent behavior, so an agent has enough to call it correctly but not full situational awareness.

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%, but the description fully explains the non-obvious parameter: `parent` takes a task id, or null to detach. The `id` parameter is only implied ('a WEEEK task') rather than described as the task being moved. This compensates for most, but not all, of the schema gap.

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

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

The description states a specific verb+resource combination: making a WEEEK task a subtask of a given parent, plus the inverse detach operation. An agent knows exactly what state change this produces. It doesn't explicitly differentiate from the nearest siblings (weeek_move_task, weeek_update_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?

The description implicitly covers both directions of use by explaining that parent:null detaches the task, which is genuinely useful routing information. However, it never says when to prefer this over weeek_move_task or weeek_update_task, nor states prerequisites such as the parent task needing to exist or be in a compatible project.

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 does well: it discloses replace-vs-merge semantics for tags ('replaces; an empty list clears'), custom-field merge behavior ('null clears; other fields keep their values'), a hard API constraint ('the API refuses one alone'), and a silently ignored field. It stops short of covering auth/permission requirements or what is returned after a successful update.

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

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

One dense but front-loaded block: purpose first, then per-field semantics, then exclusions. Every clause carries information — enum values, defaults, clearing behavior — and there is no filler or repetition of the schema's enum lists for their own sake (they are cited alongside behavioral consequences).

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

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

For a 9-parameter mutation tool with no output schema and sparse schema descriptions, the description covers the mutation surface, edge cases, and sibling routing well enough to call correctly. It would be complete at 5 with a note on partial-update behavior (omitted params are untouched) and any permission requirements.

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 22%, and the description compensates substantially: it reveals accepted formats (natural-language dates for due/start, duration in minutes, tags by name or id), the interaction rule between start and due, and a detailed semantics map for the nested `fields` object that goes beyond the schema's type-level anyOf. The only gap is `id`, which the description never characterizes as the target task identifier.

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

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

Opens with a specific verb+resource ('Update a WEEEK task') and then enumerates exactly which attributes are mutable: title, due/start, priority, type, duration, tags, custom fields. It also draws boundaries against siblings by naming that assignees, watchers, parent and projects 'have their own tools,' so an agent can distinguish this from weeek_add_assignees or weeek_set_task_parent immediately.

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 when-not guidance: 'Description is NOT updatable — the API ignores it; set it on create,' which routes the agent to weeek_create_task for that case. It also names the specific sibling tools that own assignees, watchers, parent and projects, and flags a plan-level caveat ('some plans refuse start dates') that affects whether the call should be attempted at all.

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

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

No annotations are provided, so the description carries the full burden. It explicitly states the tool returns the server name and version, which implies a read-only operation with no side effects. For a simple version query, this is sufficient behavioral 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 action and purpose without any filler. Every word earns its place, and there is no redundant 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?

Given the tool's trivial nature (no parameters, no output schema, no annotations), the description is complete. It specifies both the return value (server name and version) and the reason (to check the build), leaving no gaps for an agent to correctly 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 tool has zero parameters, and the schema shows an empty properties object. The description does not need to explain parameters. With 0 params, the baseline for parameter semantics is 4, and the description adds no unnecessary detail.

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 returns the MCP server's name and version, which precisely identifies its function. It distinguishes itself from sibling tools that operate on projects, tasks, or members, as no other tool provides version information.

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

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

The description gives clear context: the tool is for checking which build is running. It does not explicitly mention when not to use it or alternatives, but given its unique purpose, no exclusion is necessary. This aligns with 'clear context, no exclusions'.

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