Done Bear MCP

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

The description adds substantial behavior beyond annotations: the server downloads and verifies the URL, the model never sends file bytes, retries are safe with a stable idempotency key, and hard constraints (10 attachments, 10 MB, allowed types) are listed. The destructive 'remove' behavior matches destructiveHint=true.

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 sequence of tight sentences front-loads the core action and then covers add/remove behavior, retry guidance, read alternative, and constraints. Every sentence adds operational value and 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?

For a dual-action tool with a visible output schema and complete parameter descriptions, the description covers all operational essentials: mechanics, constraints, retry semantics, allowed file types, and the sibling for reading attachments. Nothing required for correct invocation is left to guesswork.

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 parameters; the description enhances key ones by clarifying the HTTPS requirement, idempotency semantics, and what 'remove' targets. It doesn't exhaustively restate every parameter, but it adds meaning beyond the schema without needing to.

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 pair, 'Add a file to a task or remove one,' and then disambiguates the two action modes. It also names the read alternative (task_show), making it easy to tell this attachment tool apart from the listed siblings.

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 when to use add versus remove, how to make retries safe via idempotency_key, and points to task_show with include: ['attachments'] for reading files. This is direct when/when-not guidance with a 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?

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, so the safety profile is covered. The description adds useful behavioral context: it returns a snapshot, includes only the latest few recent tasks, and is the sole resolver for projects/labels/teams/members. It does not detail pagination or exact response shape, but the output schema exists and the read-only nature is already annotated, so the added context is sufficient.

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 dense paragraph that front-loads the core purpose and scope, then adds usage guidance and sibling routing. It is slightly long but every sentence earns its place: the first sentence defines the snapshot contents, the second clarifies the resolver role, and the third gives explicit when-not-to-use guidance. 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?

For a read-only snapshot tool with a rich output schema and full schema coverage, the description covers the essential context: what the tool returns, when to use it, and how it differs from siblings. It does not mention pagination or the exact meaning of 'recent', but the output schema and the explicit 'latest few' caveat make the tool callable correctly. A small gap is the lack of detail on how the timezone parameter affects the snapshot, but that is documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds minimal parameter-level meaning beyond the schema, though it does clarify the tool's overall scope. The timezone parameter's warning about UTC misclassification is in the schema, not the description. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 a snapshot') and resource ('current workspace'), enumerates exactly what is included (task counts per view, recent open tasks, projects, labels, teams, members), and explicitly distinguishes itself from sibling tools like task_list, search, and task_show. It also clarifies that it is the only tool for resolving projects/labels/teams/members by name, which fully disambiguates it from siblings.

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 when-to-use guidance: use it to answer what is in the workspace and to resolve entities by name, and explicitly warns not to use it as a warm-up before every turn. It also names the alternatives for tasks (task_list, search, task_show) and states that the recent tasks here are only the latest few, so an agent knows when to prefer those siblings.

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 only indicate a mutating, non-read-only operation; the description adds crucial behavioral detail: titles are not unique, repeated calls with the same title create duplicates, and only the label itself is created. It does not discuss idempotency_key behavior or permissions, but those are partially covered by the schema 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?

Three sentences, each earning its place: first states the core action and return value, second routes to alternatives, third warns about duplicates. Information is front-loaded and there is no filler.

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

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

Given the simple tool shape, full parameter descriptions, and an output schema, the description covers purpose, scope, return value, duplicate behavior, and sibling integration. An agent has enough information to call it correctly and avoid common mistakes.

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 useful semantics for the `title` parameter: non-uniqueness, duplicate risk, and reuse guidance. It does not elaborate on `workspace` or `idempotency_key`, but the schema already documents those clearly.

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: 'Create a new label in the workspace and return its id.' It also distinguishes itself from sibling tools by saying 'Only creates the label' and pointing to task_add/task_edit for attaching it, making its scope 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 explicit when-to-use guidance: if the goal is to attach a label to a task, use task_add or task_edit instead. It also instructs the agent to check existing labels via get_context and reuse one, preventing unnecessary duplicate creation.

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, and the description adds valuable behavioral detail: default search over every state including completed/archived, multi-word matching in any order, and the ranking algorithm. This exceeds what the structured annotations alone provide.

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 search function, then gives behavioral specifics, then usage alternatives. Every sentence earns its place, and there is no redundant or filler content.

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 search tool with a complete input schema and an output schema, the description is sufficient: it covers default behavior, ranking, workspace scope, and sibling routing. Missing details like rate limits are not essential for reliable invocation.

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

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

Schema coverage is 100%, so a baseline of 3 is appropriate, but the description adds meaningful semantics by explaining query matching behavior, ranking, and the default state scope. It does not restate every parameter, which is acceptable given the schema already documents them thoroughly.

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 ('Search tasks across the workspace') and details the lexical search behavior, including ranking priority and match types. It clearly distinguishes this tool from the siblings task_list and task_show by naming them explicitly.

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

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

The description gives explicit when-to-use guidance: use search when the user names a task by its words. It also names alternatives (task_list for browsing views, task_show once the task number is known), leaving no ambiguity about routing.

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?

Discloses important behavioral details beyond annotations: default placement in Today, timezone-dependent resolution of 'today' (UTC fallback), three exceptions that change the default view (deadline, missing timezone, project/team), checklist order preservation, and that the result names the landed view. Annotations are minimal (all false), so the description carries the full burden and succeeds.

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 yet information-dense. Every sentence contributes: purpose, view behavior, timezone caveat, date format, optional fields, checklist handling, result naming, and sibling routing. It front-loads the core purpose and key behavioral caveats before enumerating options. No filler or redundancy.

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

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

Given 13 parameters, an output schema, and minimal annotations, the description covers all critical operational details: default behavior, exceptions, timezone handling, date format, optional fields, checklist semantics, result content, and when to use alternatives. An agent can confidently invoke this tool without ambiguity. The output schema handles return details, 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?

Schema coverage is 100%, so the baseline is 3. The description adds substantial semantic value: explains `when` enum behavior with default and exceptions, clarifies that `timezone` must be passed to resolve 'today' correctly, notes checklist order is preserved, and mentions idempotency_key makes retries safe. It goes well beyond the schema's per-property 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 'Create a new task' – a specific verb and resource. It immediately differentiates from sibling tools by explicitly naming task_edit, checklist, and search as alternatives for modification, sub-items, and existing-task discovery. No ambiguity about what this tool does.

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 when-to-use guidance: 'This only creates: to change a task that already exists use task_edit (fields) or checklist (items), and search first when the user may be describing a task they already have.' It also explains the `when` parameter's role in GTD views and when to pass `when: "inbox"` for captures. The timezone requirement is clearly stated with a reason.

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 include destructiveHint=true, but the description adds crucial detail: tasks move to the Trash view, leave working lists, and remain readable there. It also clarifies that archiving is not completing, which prevents misuse, and requires user confirmation before acting.

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?

Four sentences, each carrying distinct value: action, effect, differentiation from task_done, and confirmation requirement. No wasted words, and the most important action 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 tool with an output schema and rich annotations, the description fully covers purpose, behavior, alternatives, and user-confirmation requirements. Nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for the 'tasks' parameter by noting it supports batch archiving (max 50) and that one call changes every task in the list, plus the requirement to confirm the list first. This goes beyond the schema's property 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 clearly states the action ('Archive a task') and distinguishes it from sibling tools by explicitly contrasting with task_done ('use task_done for work that was finished'). It also specifies the effect (move to Trash view), leaving no ambiguity about what the tool does.

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 when-to-use guidance ('only for tasks the user wants gone') and when-not-to-use ('use task_done for work that was finished'). Also instructs the agent to confirm with the user first, which covers a key gatekeeping requirement.

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 only say the tool is not read-only and not destructive, so the description adds meaningful behavior: completed tasks move to the Logbook view, and a batch completion is effectively one call affecting every task with a slow per-task undo path. This is useful contextual disclosure beyond the structured 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 short sentences, each earning its place: the core action, the destination view, and the batch confirmation warning. The most important use case is front-loaded and there is no filler.

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

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

The tool is simple enough that the description, combined with the fully documented schema and output schema, covers everything an agent needs: what to do, batch limits, user confirmation, post-completion destination, and reversal via task_reopen.

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

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

Schema description coverage is 100%, and the schema already explains `task`, `tasks`, maxItems 50, context requirements, and workspace. The description repeats `tasks` and max 50 but adds no new parameter-level meaning, so baseline 3 applies.

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: 'Mark a task as complete.' It also clearly covers the batch variant via `tasks`, mentions the max of 50, and names `task_reopen` as the inverse operation, distinguishing this tool from siblings.

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 tells the agent when to use the batch path ('several at once with `tasks`'), warns about the undo cost ('undone one task_reopen call at a time'), and instructs confirming the list with the user first. The alternative for reversal is named directly.

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?

Even though annotations already mark the tool as non-read-only and non-destructive, the description adds substantial behavioral detail: partial update semantics ('omitted fields are left untouched'), clear-flag usage, notes replacement (no append), batch edit behavior, irreversibility, and the need for user confirmation. This goes well beyond the annotations and is valuable for safe invocation.

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 dense but well-structured, leading with the core purpose and then layering edge cases and routing guidance. Every sentence contributes, though it is long enough that an agent must read carefully. It is not bloated, just thorough.

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 15-parameter tool with batch semantics, the description covers the critical gotchas: partial updates, clear list, notes replacement, assignee behavior, label operations, batch irreversibility, and sibling tool routing. An output schema exists, so return-value documentation is not needed. The description is complete 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?

Schema coverage is 100%, so the baseline is 3. The description does reinforce key parameter behaviors (e.g., 'clear' vs empty string, notes replacing existing), but most of the parameter meaning already lives in the schema. It adds marginal but not transformative 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?

The description states a specific verb ('Update') and resource ('one task or several at once'), and explicitly distinguishes itself from sibling tools by saying it does not change status or checklist items. This is a textbook example of 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 explicit when-to-use ('Update fields on one task or several'), when-not-to-use ('For status changes use task_done, task_reopen or task_archive, and for checklist items use checklist'), and even operational guidance ('confirm the list with the user first' for batch edits). This covers both alternatives and user-facing workflow.

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?

Discloses behaviors beyond the readOnlyHint/destructiveHint annotations: ordering rules (recency; completion time for done tasks), view/state overrides for logbook and trash, search-based reordering, and pagination semantics (limit/hasMore/nextCursor). This gives the agent a clear model of what happens and what to expect.

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 dense yet efficient: every sentence covers a distinct aspect (purpose/ordering, filtering semantics, pagination, sibling routing). It is front-loaded with the primary action and resource, and contains no filler or redundancy.

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

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

With a rich output schema and read-only annotations present, the description fills the important gaps: ordering, view/state interplay, pagination, and alternative tool routing. An agent has enough context to call the tool correctly for filtering and paginated iteration without further clarification.

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 baseline is 3. The description adds meaning beyond the schema by explaining how ordering is affected by state/view, how `search` changes the result order, and how `cursor`/`limit` pagination behaves. It does not repeat parameter defaults or types, which the schema already covers.

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 ('List') and resource ('tasks in the workspace'), plus the ordering behavior (most recently updated first). Explicitly distinguishes itself from sibling tools by pointing to 'search' and 'task_show', so an agent can tell them apart 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 routing: 'To find a task by its words across every view use search instead, and task_show for one task's checklist, comments and files.' It also clarifies when to use logbook/trash views and how the `search` param interacts with the existing filter, leaving no ambiguity about selection.

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 non-read-only and idempotent, so the description adds useful behavioral detail: each task 'returns to its previous view' and batch size is capped at 50. It does not discuss permissions or error behavior, but the annotation coverage lowers the burden.

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 short sentences with no filler. It front-loads the primary action and resource, states the batch option and limit, and closes with the behavior of reopening. 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?

Given the rich input schema, annotations, and output schema, the description is complete enough. It covers the main use case, batch mutation behavior, result semantics, and the completed-task prerequisite. Nothing essential 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%, so the baseline is 3. The tool description adds value by clarifying that `task`/`tasks` must refer to completed tasks and by restating the batch limit. The `context` and `workspace` parameters are fully documented in 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?

The description uses a specific verb ('Reopen') and resource ('completed task'), and adds the qualifier 'completed' to distinguish it from related task-mutation siblings like task_done. It also explicitly covers the batch variant with `tasks`, so an agent knows exactly what operation this tool performs.

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 usage context: use this tool for completed tasks, and use the `tasks` variant for reopening several at once up to 50. It does not explicitly name alternatives or state when not to use it, but the 'completed task' scope is sufficient guidance for most cases.

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

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

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.