Done Bear MCP

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

Beyond the annotations, the description discloses significant behavior: the server downloads the file rather than the model sending bytes, it verifies size and type, idempotency protects against duplicate uploads, and remove deletes the attachment. This is rich, accurate behavioral context and is consistent with the destructiveHint and readOnlyHint 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?

The description is front-loaded with the core purpose and then efficiently layers operational details, constraints, and usage guidance. Each sentence adds necessary information without padding or repetition.

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 two-action complexity, the description covers the critical behavioral details: server-side fetching, idempotency, deletion semantics, limits, allowed types, and the alternative for reading attachments. An output schema exists, so not detailing return values does not hurt completeness.

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 already 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the effect of action values, the safety semantics of idempotency_key, and the distinction between url and attachment. It does not deeply explain every parameter like context or workspace, but the schema handles those adequately.

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 clear verb and resource: 'Add a file to a task or remove one.' It states the two modes of operation and explicitly points to task_show as the tool for reading attachments, distinguishing it from 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?

The description gives concrete guidance on when to use add vs remove, explains retry behavior with idempotency_key, and explicitly routes read-only attachment access to task_show. It also sets boundaries with limits on count, size, and allowed file types.

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?

Beyond the destructiveHint annotation, the description discloses key behaviors: added items are appended unchecked, `titles` preserves order, parallel adds land in arrival order, edit can rename and/or toggle completion, and remove deletes one item. This gives an agent an accurate mental model of side effects.

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

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

The description is compact and front-loaded with the tool's purpose, then efficiently explains each action with relevant behavioral detail. No sentences are wasted, and the guidance about order and task_show earns its place.

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

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

The description is complete enough for an agent to call the tool correctly: all actions are defined, required item IDs are sourced from task_show, and output schema covers return values. It leans on the schema for scoping parameters like `workspace` and `idempotency_key`, which is acceptable given full schema coverage.

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

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

The schema already documents all parameters, and the description adds meaning beyond it by explaining the relationship between `title` and `titles`, the ordering guarantee, and how `completed: true/false` behaves on edit. This is substantial parameter-level value on top of high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Change the checklist on a task,' then enumerates the three supported actions (`add`, `edit`, `remove`). It also distinguishes itself from task_show by explicitly directing reads there.

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 concrete usage guidance, especially for multi-item adds: pass all titles in one call via `titles` to preserve order, instead of parallel single adds. It also names task_show as the place to read the checklist, but it does not explicitly explain when to use this over sibling tools like task_edit.

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?

Beyond the destructiveHint annotation, the description discloses attribution to the connected user, workspace-wide visibility, lack of notifications, author-only editing with an edited marker, and no-Trash permanent deletion. These are non-obvious behavioral consequences an agent must know before acting. No contradiction with 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?

The description front-loads the core purpose and then allocates one dense, informative sentence per action. Every sentence carries a critical warning or constraint; there is no filler or repetition.

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?

Covers all three action modes, permission constraints, permanence, notification behavior, and the read alternative. With an output schema present and 100% parameter coverage, nothing essential for correct selection or invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the effect and constraints of each action, such as edit requiring an owned comment and remove being irreversible. It leaves idempotency_key and comment-prefix details to the schema, which already documents them.

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

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

The description opens with a specific verb and resource ('Write on a task's comment thread') and then enumerates three concrete actions, each with distinct behavior. This clearly separates it from siblings like task_edit (which edits task fields) and task_show (which reads the thread).

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

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

It explicitly states when to use each action: add for posting visible comments, edit for one's own comments, remove for permanent deletion requiring user confirmation. It also directs the agent to the alternative read tool, task_show with include: ['comments'], leaving no ambiguity.

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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds what the snapshot contains and that it resolves names, but does not disclose deeper behavioral traits such as cost, size, freshness, or latency. This is adequate given the annotations, but not exceptional.

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

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

The description is two sentences with no filler. The first sentence front-loads the scope, and the second sentence gives selection guidance and an explicit negative usage constraint. 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?

Given the 5-parameter schema with 100% coverage, an output schema, and clear safety annotations, the description provides everything needed to select and invoke the tool correctly. It identifies the domain, the return scope, the resolver role, and the no-warm-up policy.

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

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

Schema description coverage is 100%, with all five parameters already documented in detail, including the unusual 'context' parameter requirements, timezone behavior, limits, and project status. The description adds no parameter-level information beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get a snapshot of the current workspace', and enumerates exactly what that snapshot contains. It also distinguishes this tool from siblings by stating that there is no separate list tool for projects, labels, teams, and members.

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

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

The description explicitly states when to use the tool: to answer what is in the workspace and to resolve named resources. It also gives a clear exclusion: 'not as a warm-up before every turn', which tells the agent when not to call it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds behavioral context beyond annotations: 'context is used to tailor the guide' and the session-level loading instruction, explaining how the tool behaves in use. No contradiction with 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?

First sentence states purpose, second gives usage timing, and the bullet list is scannable. The final paragraph about context overlaps with schema but adds a concrete instruction. It's longer than minimal but well-structured and front-loaded.

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

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

For a read-only reference tool with annotations and an output schema, the description covers what, when, all topic values, and context construction. Nothing needed to invoke it correctly is missing.

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

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

The schema describes 'topic' only as 'Guide topic to read', while the description gives 11 bullets explaining exactly which use cases each topic covers. For 'context', it adds a first-sentence requirement beyond the schema's already detailed instrctions. With 100% schema coverage, this extra guidance clearly raises the score.

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: 'Read Done Bear's guide for one topic' and explains what the guide contains (what the data means, relation to product, how to use it). The bullet list clearly disambiguishes this reference tool from the operational siblings by mapping topics to concrete task types. No tautology or ambiguity.

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

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

Gives an explicit trigger: 'Load a topic before doing that kind of work for the first time in a session.' This tells the agent when to call. It doesn't name alternatives or exclusions, but the tool's unique role among siblings makes that unneeded.

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 indicate readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds only the workspace scope and no additional behavioral context such as duplicate handling, side effects, or restrictions, but it does not contradict 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?

The description is a single, clear sentence with no filler. It front-loads the action and the resource and is appropriately sized for a simple label-creation 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 full schema coverage, an output schema, and annotations, the description is minimally sufficient for invoking the tool. It lacks routing guidance versus label_add and does not mention any labeling constraints, leaving a small but notable 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?

Schema description coverage is 100%, so the schema already documents both required parameters fully. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline.

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

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

The description uses a specific verb ('Create') and names a clear resource ('a new label') with workspace scope, so an agent can understand the core action. It does not, however, distinguish itself from the sibling tool label_add, which may overlap in intent.

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 no guidance about when to prefer this tool over label_add, label_list, or label_remove, nor any prerequisites or uniqueness constraints. The appropriate usage is only weakly implied by the word 'Create'.

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 flag this as non-read-only and destructive, and the description enriches that with concrete behavior: edits are partial ('only the fields given change'), empty strings clear description/target_date, and join/leave mutate sidebar membership. No contradiction with the annotations exists.

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 front-loaded with the core purpose and each subsequent sentence earns its place by explaining one action or a key edge case. It is dense but compact, with no filler or repetition of schema 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 9-parameter tool with four actions, the description covers all behavioral decisions the agent must make, while the rich schema and output schema cover remaining parameter details and return values. It even names the read alternative to complete the workflow picture.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful semantics beyond the schema by explaining the action enum and partial-update/clearing behavior. It does not duplicate every parameter but focuses on the non-obvious action-dependent constraints.

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 pair ('Create or change a project') and then enumerates the four distinct actions (add, edit, join, leave) with their exact effects. This clearly differentiates the tool from siblings like get_context and task_add by resource and operation type.

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 explicit action semantics and tells the agent when to use the read alternative: 'Read projects with get_context.' Each action's precondition (add requires name; edit, join, leave target the named project) is stated, so there is little ambiguity about when to invoke this tool.

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 mark the tool as read-only and non-destructive. The description adds substantial behavioral detail beyond that: exact, prefix, word-boundary, substring, and fuzzy matching, recency/status weighting, and unordered multi-word queries. There is no contradiction with 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?

The description is three sentences with no filler. It front-loads the core purpose, then packs ranking behavior and multi-word matching into compact, informative phrases. Every sentence earns its place.

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

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

The combination of a fully-described schema, output schema, and read-only annotations covers the supporting details such as limits, state, cursor, timezone, and workspace. The description supplies the one thing structured data cannot: the exact ranking and matching semantics. Nothing essential is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all seven parameters. The description reinforces that queries match title and description but adds no parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with a specific verb and resource: 'Search tasks across the workspace.' It then details the ranked lexical search over title and description, which clearly distinguishes this tool from sibling tools like task_list or task_show. The operation and scope are 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?

The description makes the usage context clear: use when a ranked, lexical search across task titles/descriptions is needed. It does not explicitly name alternatives or state when not to use it, but the search-focused language and ranking details imply the distinction from list/show 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?

Description discloses important behavior beyond annotations: new tasks default to Today, the default depends on timezone and falls back to UTC, and checklist order is preserved exactly. This adds material context on top of the minimal `readOnlyHint: false` and `destructiveHint: false` 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?

The description is front-loaded with 'Create a new task' and each subsequent sentence addresses a real usage pitfall. A small amount of redundancy with the schema's parameter descriptions, such as checklist order, keeps it from a perfect score.

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 13-parameter creation tool with an output schema and 100% schema coverage, the description covers the most consequential behaviors: default view, timezone sensitivity, and checklist use. The remaining parameters are well documented in the schema, leaving no critical gap for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters. The description adds useful emphasis on `when`, `timezone`, and `checklist`, but mostly reinforces schema details rather than introducing new semantics, so the baseline of 3 is appropriate.

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

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

The description opens with 'Create a new task,' a specific verb and resource that clearly identifies the operation. It provides enough task-creation context to differentiate from task_edit and task_done, though it never explicitly names a sibling or states what it is not.

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

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

Clear practical guidance is given: pass `when: "inbox"` for captures not committed to today, always include `timezone` to resolve today correctly, and use `checklist` in one call for sub-items. No explicit alternatives or exclusions are stated, but the context strongly implies this is for new tasks rather than modifications.

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 flag destructiveHint=true and readOnlyHint=false; the description adds useful specifics: tasks move to the Trash view, are removed from every working list, and up to 50 can be archived in one call. This enriches the annotation signal without contradicting it.

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

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

Three short sentences cover the action, the batch variant, the effect, and the user-confirmation requirement. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a destructive, batch-capable tool, the description covers the action, scope, effect, and confirmation requirement. The output schema handles return-value details, so nothing critical is missing, though it could briefly note recoverability from the Trash for extra safety clarity.

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

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

The input schema already documents all parameters at 100% coverage, including the distinction between `task` and `tasks` and the maxItems=50 constraint. The description adds minimal new parameter-level meaning beyond restating the batch limit.

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 ('Archive') and resource ('task'), and clarifies both single and batch variants. The effect of moving items to the Trash view and out of all working lists clearly distinguishes it from sibling tools like task_done, task_edit, and task_reopen.

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 clear context: use for archiving tasks, supports batching via `tasks`, and explicitly requires user confirmation first. It does not name sibling alternatives, but the purpose and preconditions are clear enough for an agent to know when to invoke it.

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

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

With annotations providing only readOnlyHint=false, openWorldHint=false, and destructiveHint=false, the description adds meaningful behavioral context: completion moves tasks to the Logbook view, and batch completion requires one reopen call per task to undo. This clarifies the real-world consequence of the mutation and the reversibility profile beyond the annotation flags.

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

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

The description is three tight sentences with no filler. The core operation is front-loaded, the batch behavior is stated next, and the caveat about undo cost and user confirmation is placed last. Every sentence carries relevant 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 output schema exists, the description does not need to explain return values. It covers the operation, batching rules, state transition, and the undo workflow. It is slightly less explicit about when not to use this tool in favor of siblings, but the essential context for a correct call is 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 100%, so the baseline is 3, but the description adds useful parameter-level meaning by explaining the batch consequence of `tasks` and why confirming the list is important. It also reinforces the max-50 constraint already present in the schema, while leaving `task`, `context`, and `workspace` semantics to their already thorough schema descriptions.

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

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

The description opens with a specific verb+resource combination, 'Mark a task as complete', and immediately covers the batch variant with `tasks`. It also distinguishes the tool from siblings by explaining completed tasks 'move to the Logbook view' and mentioning `task_reopen` as the undo path, so an agent can tell it apart from `task_archive`, `task_edit`, and related tools.

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

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

The description clearly states when to use `task` versus `tasks`, caps the batch at 50, and instructs confirming the list with the user first. It references `task_reopen` as the reversal mechanism, giving useful scoping context, though it does not explicitly enumerate when to prefer sibling tools such as `task_archive` or `task_edit`.

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 state idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds important behavioral context: partial update semantics (omitted fields untouched), replace-don't-append for notes, clear for removal, batch applies same changes and cannot be undone. One could expect destructiveHint possibly true for batch, but description explicitly warns it cannot be undone. It doesn't cover auth/permissions, but for a task-editing tool this is adequate.

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 compact and front-loaded: first sentence states core purpose, then covers the main behaviors in a few sentences. Every sentence adds useful information; 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 tool with 15 parameters and complex batch behavior, the description covers the key semantics: partial updates, clear, notes replacement, label changes, batch behavior, max 50, and user confirmation. Output schema exists, so return values don't need description. Complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so schema itself documents all parameters. Description adds value by mapping semantics: mentions `clear` removes value instead of empty string, notes replace existing, assignee assign/clear, add_labels/remove_labels change labels, tasks max 50. This goes beyond the schema descriptions, especially for behavior of omitted fields.

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

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

Description says explicitly: 'Update fields on one task or on several at once', distinguishing `task` vs `tasks`, and listing what is changed and what is not. It differentiates from siblings like task_add (create), task_done, task_archive, task_reopen by focusing on editing 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?

Provides explicit usage guidance: use `task` for a single task, `tasks` for batch up to 50, use `clear` to remove values rather than empty strings, confirms batch changes with user first. Also names `label_create` as prerequisite for add_labels. This gives clear when-to-use and alternatives/related 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?

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavior beyond that: recency ordering, completion-time ordering for done tasks, logbook/trash overriding `state`, and `hasMore` pagination behavior. No contradiction with 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?

Three dense sentences with no filler: the core action and ordering are front-loaded, followed by filter semantics and then pagination. Every sentence adds distinct value and nothing merely repeats schema fields.

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 rich schema and a stated output schema, the description covers the essential invocation knowledge: filtering, ordering, override behavior, and pagination indicators. Remaining details like `cursor` and `timezone` are already documented in their parameter descriptions, so nothing critical 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 description enriches the schema meaningfully: it interprets `view` values, warns that logbook/trash ignore `state`, clarifies that `search` ranks matches within the filter and changes ordering, and ties `limit` to `hasMore`. These are non-obvious semantics an agent could not reliably infer from enum names and schema descriptions alone.

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

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

The description clearly identifies the action and resource ('List tasks in the workspace') and adds concrete ordering and filtering details. It does not explicitly contrast itself with sibling tools like `task_show` or `search`, so it lacks explicit sibling differentiation.

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

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

The description gives useful operational context: view semantics, logbook/trash overriding `state`, and `search` changing result ordering. However, it never states when to prefer this tool over siblings such as `search` or `task_show`, leaving alternative selection implicit rather than explicit.

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

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

Annotations already show this mutation is idempotent and non-destructive. The description adds useful behavioral context beyond annotations: each reopened task 'returns to its previous view' and batch calls are capped at 50. No contradiction exists between the description and 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?

The description is a single, front-loaded sentence that covers the action, the batch option, the limit, and the key effect. There is no filler or redundant detail, and every phrase earns its place.

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

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

Given the complete schema coverage, the provided annotations, and the existence of an output schema, the description sufficiently explains the tool's purpose and primary behavior. The user-confirmation requirement for `tasks` is handled in the schema rather than the description, which is acceptable, so only minor additional context such as explicit state-change consequences is missing.

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

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

Schema description coverage is 100%, and every parameter already has a meaningful description in the input schema. The tool description restates only the max-50 limit and the choice between `task` and `tasks`, which does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Reopen a completed task.' It also adds the batch variant via `tasks` and the outcome 'Each returns to its previous view,' which clearly differentiates it from sibling tools like task_done and task_edit. Even without naming alternatives, the purpose is unambiguous.

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

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

The description clearly indicates when to use the tool: for reopening completed tasks, either singly or in batches. It does not explicitly mention exclusions or alternatives, such as 'do not use for archived tasks' or 'use task_done for completing instead,' so it lacks full when-not guidance but provides solid contextual usage.

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 readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds valuable behavior beyond that: comments come oldest first with author and edit status, attachments each include a short-lived signed URL, and optional sections are extra round trips.

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 carry substantial information with no filler. The main purpose is front-loaded first, and the include details are efficiently placed in the second sentence.

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

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

For a read-only detail tool with a rich output schema and fully described parameters, the description is complete. It covers scope, optional sections, and their behavioral characteristics; nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description enhances the 'include' parameter specifically by explaining what each value returns and the extra-read cost, which is meaning beyond the schema's generic description.

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

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

The description states a specific verb ('Get full details') and resource ('a single task') and enumerates what is included: fields, labels, and checklist items. It distinguishes itself from list-oriented siblings by emphasizing it targets one workspace-scoped task number.

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

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

The description gives clear guidance on when to add the 'include' parameter: only for comments or attachments that cost extra reads, with 'Omit unless you need them' reinforcing restraint. It does not explicitly name sibling alternatives like task_list, but the single-task scope is clear enough for an agent to route correctly.

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