Done Bear MCP

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it explains that the server fetches the HTTPS URL rather than the model sending bytes, that size and type are verified before storage, that removal is destructive on the named attachment, and that a stable idempotency_key prevents duplicate uploads on retry. That idempotency/retry guidance is exactly the kind of behavior annotations cannot express.

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

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

Front-loaded with the add/remove dichotomy, then ordered by operational importance: fetch behavior, idempotency, read alternative, limits, allowed types. Dense and largely waste-free, though the trailing limits-and-types list reads as a compact dump rather than prose.

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?

An output schema exists, so return values need no explanation, and the description still covers the things structured fields do not: mutation semantics, the server-side download model, retry safety, quotas, and accepted file types. Nothing an agent needs to invoke this 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 already 100%, so the baseline is 3; the description adds real meaning on top by stating which parameters are required per action ('Required to add' via url, 'Required to remove' via attachment) and by explaining the reuse semantics of idempotency_key for lost-response retries. It does not clarify filename defaulting or the workspace-failure behavior, 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+resource pair in both modes ('Add a file to a task or remove one'), and the two action branches are clearly delineated with their own parameter requirements (url for add, attachment for remove). It also names the sibling used for the read path (task_show), so an agent can separate this tool from task_show without inspecting either schema.

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

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

Gives conditional routing for both branches, names the alternative for reading attachments ('Read a task's files with task_show and include: ["attachments"]'), and supplies concrete hard limits (10 attachments per task, 10 MB per file, allowed MIME types) that determine whether the call should be made at all.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description is consistent with that ('remove deletes one'). Beyond the annotations it discloses real behavior: appended items land unchecked after existing ones, and titles preserves order while parallel single adds land in arrival order. It omits auth/workspace prerequisites and retry semantics, which the schema covers.

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

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

Front-loaded with the purpose, then organized action-by-action, and the closing sentence points to the read path. The parenthetical about parallel single adds is slightly tangential but conveys a genuine ordering caveat, so it earns its place.

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

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

For a 9-parameter mutation tool with an output schema, the description covers the operation semantics and where to read state, leaving workspace, idempotency, and return shape to structured fields. Nothing essential for correct invocation is missing, though prerequisites like workspace selection are not echoed.

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, but the description adds meaning beyond it: the title/titles choice, the ordering guarantee for titles versus parallel adds, and completed:true/false as check/uncheck on edit. The item parameter's role for edit/remove is left to 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 opening sentence names a specific verb and resource ('Change the checklist on a task') and the action breakdown makes each operation concrete. It distinguishes itself from siblings by routing reads to task_show, so an agent can separate mutation from inspection without opening either schema.

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

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

It states what each action does and names task_show as the way to read item ids and state, which is the key alternative. It also guides batching ('pass every title for a multi-item list in one call'). It stops short of explicit when-not-to-use or prerequisite conditions such as the multi-workspace 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 give the generic destructive/write profile; the description adds real behavioral context: attribution to the connected user, workspace-wide visibility, no notification sent, permanent deletion with no Trash, and the 'edited' marker on rewrites. It also warns that the audience is teammates, not the invoking user.

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

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

Front-loads the resource, then handles actions in enum order with the destructive one last and the most cautionary detail attached to it. Every clause adds operational information; nothing is restated from the title or schema.

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

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

An output schema exists, so return values need no explanation, and the 7-parameter surface is the only complexity left. The description covers the mutation lifecycle, audience, and reversibility, which is everything an agent needs to call it safely.

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 maps action values to their parameter requirements by implication (body to post/rewrite, comment to edit/remove, task to all) and clarifies intent behind the destructive path. It stops short of explaining the UUID-prefix matching or idempotency semantics, which stay 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?

States a concrete verb and resource ('Write on a task's comment thread') and then enumerates the three actions with their distinct effects. It explicitly distinguishes itself from task_show, which is named as the read path, so an agent can route without opening a sibling schema.

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

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

Each action carries its own when-to-use condition: add for posting a workspace-visible message, edit restricted to your own comment, remove only after user confirmation. It also names the alternative for reading the thread (task_show with include: ["comments"]), covering the when-not case.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds meaningful scope behavior beyond that: it is the only name-resolution path for projects/labels/teams/members, and it warns that returned tasks are only the latest few rather than a full task set.

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, front-loaded with what the tool returns, then its unique resolution role, then the exclusion warning and alternatives. Every sentence carries distinct routing value and nothing is redundant.

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

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

With an output schema present, annotations covering safety, and full schema coverage, the description only needs to carry the selection logic and scope caveats — which it does completely, including the multi-workspace name-resolution role and the 'latest few tasks' limitation.

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 context, timezone, workspace, tasks_limit and projects_status are all already documented with defaults, bounds and enum values. The description adds no parameter-level detail (e.g. timezone effect on view classification) beyond what the schema already states, so the 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?

Names a specific verb+resource ('Get a snapshot of the current workspace') and enumerates the contents (task counts per view, recent open tasks, projects, labels, teams, members). It explicitly distinguishes itself from siblings task_list, search, and task_show, so an agent can select it without consulting other schemas.

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

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

States when to use it ('answers what is in the workspace', 'resolves a project, label, team or member by name'), when NOT to use it ('not as a warm-up before every turn'), and routes each alternative case to a named sibling with its selection criterion.

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 declare it is a non-read-only mutator that is not destructive; the description adds a genuinely useful behavioral trait — titles are not unique, so repeated calls duplicate rather than no-op. It does not mention the idempotency_key retry-safety behavior, though the schema documents that parameter.

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: scope, follow-up routing, and the duplicate-avoidance warning. The creation semantics are front-loaded before the caveat.

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?

An output schema exists, so the description needn't detail return values, and it still notes the id is returned. For a simple create tool it covers scope, sibling routing, and the main failure mode (duplicates) completely.

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 cross-tool semantics for `title`: it is the same value passed to task_add `labels` and task_edit `add_labels`, and it is non-unique. It does not elaborate on `workspace` or `idempotency_key`, 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+resource ('Create a new label in the workspace') and even names the return value (its id). It explicitly distinguishes itself from sibling tools task_add and task_edit, which it says must be used afterwards to attach the label.

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

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

Gives explicit when-to-use routing: this tool only creates, and attaching requires task_add `labels` or task_edit `add_labels`. It also prescribes a check-first workflow (consult get_context's labels and reuse an existing one) before calling.

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, so the bar is lower, yet the description adds real context: edit is a partial update, only supplied fields change, and an empty string explicitly clears description or target_date. It does not disclose permission requirements or the effect of leave on existing project data.

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 tight sentences, front-loaded with the core purpose, then action semantics, then clearing behavior, then the read alternative. No filler or restatement.

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

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

For a 9-parameter mutation tool with an output schema and full schema description coverage, the description covers the action space, partial-update and clear semantics, and the read alternative. Minor gaps remain around workspace/auth preconditions, but the schema handles those.

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 baseline is 3, but the description meaningfully expands the terse action enum ('What to do with the project') into concrete semantics for each value, and restates the name-required-on-add rule. It adds value beyond the schema for the central parameter.

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 pair and resource ('Create or change a project') and then enumerates the four action values with their distinct effects, so an agent can distinguish add/edit/join/leave without opening the schema. It also names get_context as the read path, separating this mutation 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?

Gives explicit per-action conditions ('add' creates, 'edit' updates, 'join'/'leave' toggle sidebar membership) and routes reading to get_context. It stops short of stating when not to use the tool (e.g., permissions or prerequisites for joining), so it is strong but not fully complete.

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 this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds non-obvious behavior on top: every state is searched by default including completed and archived, results are ranked by match class with recency and status as tiebreakers, and multi-word queries match in any order. These are exactly the surprises an agent would otherwise get wrong when interpreting results.

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?

Five sentences, each carrying a distinct payload: identity, ranking behavior, multi-word handling, default state scope, and sibling routing. The ranking sentence is the longest but is the tool's core differentiator, and the routing instruction is correctly placed last as a disambiguation. No filler or repetition of the tool title.

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?

An output schema exists, so return values and the nextCursor pagination contract need not be restated. With 100% schema coverage on all seven parameters, annotations covering the safety profile, and the description covering ranking semantics, default scope, and sibling routing, an agent has everything needed to call this 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 baseline is 3 and the schema already documents limit, cursor, state, timezone, workspace, and context. The description goes beyond that baseline by explaining what the query string actually matches against and how multi-word queries are combined, which is real semantic value for the primary parameter.

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

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

States a specific verb and resource ('Search tasks across the workspace') and immediately narrows it to a ranked lexical search over title and description, which is a distinct mechanism from browsing. It explicitly names the siblings task_list and task_show and the condition that distinguishes them, so an agent can route without opening any schema.

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

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

Gives an explicit trigger ('when the user names a task by its words') and names two alternatives with their own triggers: task_list to browse a view such as Today or Inbox, and task_show once the task number is known. When-to-use and when-not-to-use are both present, with no inference required.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds real value beyond that: the exact return contract ('only key metadata and the exact agent UUID or null'), the inactive-agent case with disabledAt, and the auth/membership prerequisites. It stops short of describing failure behavior when no binding exists or when membership is stale.

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 tight sentences, front-loaded with the verb+resource and scope, then return contract, then prerequisites, then the sibling handoff. No filler and nothing buried.

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

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

An output schema exists, so the description needn't document the return payload in full, and it still sketches it usefully. Prerequisites, sequencing, and exclusions are all covered. Minor gap: no mention of what an agent should do when the read returns null (i.e., proceed to register) or when membership checks fail.

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

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

Schema coverage is 50%: context is fully documented in the schema, workspace_id has only a format/pattern. The description says 'one explicit workspace', which confirms workspace_id scoping but adds no syntax, format, or default detail beyond the schema's UUID pattern. With the schema doing most of the work, a 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?

States a specific verb and resource ('Read the task-agent identity bound to this connection's existing API key') plus the scoping constraint ('in one explicit workspace'). It also explicitly distinguishes itself from the sibling task_agent_register, so an agent can route correctly without opening either schema.

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

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

Gives explicit sequencing guidance ('Use this before task_agent_register and retain key.id as expected_key_id') and clear exclusions ('Does not register, assign or start any task'). Preconditions (API-key connection, current workspace membership) are stated rather than implied.

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

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

Annotations already declare idempotent=true and destructive=false, but the description adds substantial behavioral context beyond them: same key/workspace/name retries return the same UUID, and conflicting or inactive bindings fail without takeover or reactivation. It further clarifies side-effect boundaries ('creates no key, changes no scope'), which the annotations alone do not convey.

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

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

Front-loaded with the core action, then layered constraints, prerequisites, and exclusions in a single dense paragraph. Every clause carries information, though the density is high enough that it reads more like a spec block than prose.

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 prerequisites, required ordering, idempotency semantics, failure behavior, and explicit exclusions. Since an output schema exists, the description need not explain return values, and 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?

With only 25% schema coverage, the description compensates well: it explains the origin of expected_key_id (key.id from task_agent_get), the workspace-scoping role of workspace_id, and the role of name in retry idempotency. The context parameter is not addressed here, but it carries its own detailed schema description, so the gap is minor.

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

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

States a specific verb and resource ('register one assignable task agent') scoped to 'this connection's existing key in one workspace,' and explicitly delimits against siblings by declaring it does not 'assign/import/start tasks.' An agent can distinguish it from task_add and task_agent_get without opening either schema.

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

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

Gives explicit preconditions ('after the user approves that durable binding,' write-scoped API key restricted to this workspace, owner/admin membership) and sequencing ('Read task_agent_get first and pass its key.id as expected_key_id'). It also names what the tool does not do, so the when-not is covered.

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 it destructive, but the description adds the consequences that annotations cannot convey: tasks leave every working list, land in a readable Trash view (i.e. recoverable, not deleted), and a single batch call changes every task in the list. It also flags the confirmation requirement.

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 compact sentences, front-loaded with the action and the batch option, then the disambiguation, then the safety note. The only redundancy is repeating the 'max 50' cap that the schema already encodes.

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 mutation with an output schema available for return values, the description covers scope, consequences, recoverability, and required confirmation. 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?

Schema coverage is 100%, so `task`, `tasks`, `context`, and `workspace` are already documented with patterns and the 50-item cap. The description restates the max-50 limit but adds no syntax or format detail beyond the schema, so it sits at the 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?

States a specific verb (archive) and resource (task), covers the batch variant with `tasks` and its 50-item cap, and explicitly contrasts itself with task_done. An agent can distinguish it from task_show, task_edit, and task_done without opening a schema.

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

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

Gives explicit when-to-use (tasks the user wants gone), when-not (work that was finished - use task_done), a required confirmation step, and the follow-up path for retrieval (task_list `view: "trash"`). This is the full when/when-not/alternative triad.

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 declare the safety flags (readOnly=false, destructive=false, openWorld=false); the description adds substantive behavior beyond them: completed tasks move to the Logbook view, and a 50-task batch must be undone one `task_reopen` call at a time. The conflict/reload behavior for `expectedRevision` lives in the schema rather than here, which is the only missing piece.

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

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

Two sentences with no filler, front-loading the core action and the batch variant before the undo-cost caveat. Every clause carries information an agent needs.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. It supplies the batch semantics, the reversibility path, and the user-confirmation requirement, leaving only the revision-conflict flow to 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 every parameter including the `task` vs `tasks` exclusivity, the 50-item cap, and the `expectedRevision` conflict semantics. The description reinforces the max-50 and confirmation rules but adds no syntax or format detail beyond the structured fields, so the 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?

States a specific verb ('Mark...as complete') and resource ('task'), and distinguishes the single-task form from the batch form via the `tasks` parameter. It also names the sibling `task_reopen` as the inverse operation and clarifies the destination (Logbook view), so an agent can separate it from `task_archive` and `task_edit`.

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

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

Gives a clear condition for the batch path ('or several at once with `tasks` (max 50)') and a workflow rule ('confirm the list with the user first'). It does not explicitly state when to prefer this over `task_archive` or `task_edit`, so it stops short of full alternative 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description goes well beyond them by disclosing ordering rules, pagination contract (limit/hasMore/nextCursor round-trip), and the state-override behavior of logbook and trash views. That is real operational context an agent cannot infer from 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?

Front-loaded with the core action and ordering, then the filter semantics, then pagination, then sibling routing — a logical progression with no filler sentences. It is somewhat dense and partially restates the view enum already present in the schema, which is the only slack.

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 an 8-parameter list tool with a 100% documented schema and an output schema, the description covers everything an agent needs: scope, default ordering, filter precedence, search behavior, pagination, and alternatives. Nothing required to call 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, but the description adds genuine semantics: the enumerated view buckets, that logbook/trash read completed/archived regardless of state, that search reorders results by relevance rather than recency, and how cursor pairs with the same filters. Only minor duplication of schema content keeps it from a 5.

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

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

States a specific verb and resource ('List tasks in the workspace') plus the default ordering ('most recently updated first'). It also explicitly distinguishes itself from two named siblings, search and task_show, so an agent can route correctly without opening any schema.

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

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

Gives explicit routing rules: use search to find a task by its words across every view, and task_show for a single task's checklist, comments and files. It also explains the view/state interaction and the precedence rule that logbook/trash override state.

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 declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety is partly covered. The description adds real behavioral context beyond that: reopening restores the task to its previous view (prior status, not a generic default) and caps the batch at 50.

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

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

Two compact sentences, front-loaded with the action and the bulk-mode switch, with no filler. Every clause carries information an agent needs before calling.

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?

An output schema exists, so return values need no explanation, and single/batch behavior and limits are covered. Minor gap: it says 'completed task' but does not clarify whether archived tasks can be reopened, which matters given the task_archive sibling.

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 explains `task`, `tasks`, `context` and `workspace` fully. The description only echoes the `tasks` max-50 constraint and the confirm-with-user warning that the schema already contains, 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?

States a specific verb (reopen) and resource (task), plus the batch variant via `tasks` with a cap. An agent can distinguish this from task_done/task_archive/task_edit because the description makes clear it reverses completion and restores the prior state.

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?

Condition for use is implicit but clear: the task must be completed, and the `tasks` parameter is named as the bulk alternative. No explicit when-not guidance or naming of competing siblings such as 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 already declare a safe, read-only, closed-world read, so the bar is lower, and the description still adds real behavior: comments come back oldest-first with author and edited state, attachments carry short-lived signed URLs, and extra sections each cost a round trip. It does not cover failure modes such as a missing workspace resolving ambiguous choices beyond what the schema states.

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

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

Two sentences, front-loaded with the primary purpose, and the optional-cost caveat attached to the parameter it governs. 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 an output schema and read-only annotations, return shape and safety are already covered, and the description fills the remaining gap about which reads are expensive. Slightly thin on workspace-resolution behavior, which matters for a 5-parameter tool, but adequate overall.

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 3 is the baseline, but the description adds meaning the enum label alone ('Extra sections to load') does not: it explains what each include value actually returns and why it is optional. Timezone, workspace, and context semantics are left entirely to the schema.

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

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

States a specific verb and resource ('Get full details for a single task') and enumerates what those details contain (fields, labels, checklist items). The scoping key ('workspace-scoped task number') and the contrast with list-style siblings make it unambiguous which tool retrieves one record.

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 conditional guidance for the optional path: add `include` only for sections that 'cost extra reads', and names exactly which sections exist. It does not route the agent to a sibling (e.g. task_list to find the task number first), so it stops short of explicit alternatives.

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