Done Bear

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?

Goes beyond the annotations by disclosing that additions append unchecked after existing items, that `titles` preserves order while parallel single adds land in arrival order, and that edit can rename and toggle `completed`. All disclosures are consistent with destructiveHint=true and readOnlyHint=false; no contradiction found.

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

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

A single dense paragraph that front-loads the purpose and then walks through each action with inline code formatting. Every clause earns its place, though the ordering parenthetical in the second sentence packs multiple caveats into one breath.

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 100% schema coverage and an output schema for return values, the description covers the essential operational surface: all three actions, the item-identification workflow via task_show, and ordering semantics. Minor gaps remain around error behavior (e.g., unknown item prefix) but nothing an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine value on top: it ties `action` values to parameter relevance (item required only for edit/remove, completed meaningful only on edit) and clarifies the title/titles substitution. This cross-parameter meaning is not recoverable from the individual schema descriptions.

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

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

Opens with a precise verb+resource statement ('Change the checklist on a task') and enumerates three concrete operations (add, edit, remove) with their exact effects. This clearly distinguishes it from sibling task-level tools like task_add and task_edit, which operate on tasks rather than checklist items.

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 operational guidance: use a single call with `titles` to preserve order for multi-item adds versus parallel single adds, and read items and their ids via task_show before editing or removing. It does not explicitly name excluded alternatives, but the task_show pointer and action-mode breakdown make the intended workflow clear.

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

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

Beyond the destructiveHint annotation, the description discloses attribution to the connected user, workspace-wide visibility, lack of notifications, author-only edit permission, the 'marked edited' trait, and permanent deletion with no Trash. This is rich behavioral context that materially affects how an agent should invoke the tool.

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

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

The description is compact yet dense, organized by action, and front-loaded with the core purpose. Every sentence adds operational value; there is 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 destructive, three-action tool with seven parameters, the description covers each action's behavior, side effects, prerequisites, and the sibling tool for reading. The presence of an output schema means return-value documentation is already handled elsewhere, so 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 description adds meaningful semantics beyond the schema by explaining what each action value does and by advising on body tone ('write it as a message to the user's teammates rather than a note to the user'), which improves correct usage of the body 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?

The description opens with 'Write on a task's comment thread,' a specific verb and resource, and enumerates the three actions (add, edit, remove). It clearly distinguishes itself from sibling task_show, which is explicitly named for reading 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 gives per-action guidance: add is for public teammate-facing messages, edit is only for one's own comments, and remove requires user confirmation. It also explicitly routes read operations to task_show with include: ['comments'], making the when-to-use boundary precise.

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 behavior beyond that: it returns a composite snapshot and can resolve multiple entity types by name, and the warning 'not as a warm-up before every turn' hints at the cost of calling it unnecessarily.

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 at two sentences and front-loads the purpose before the usage guidance. The phrase 'answers what is in the workspace' is slightly redundant after the first sentence, but the rest of the second sentence earns its place by clarifying scope and misuse.

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 annotations covering read-only behavior, a fully documented input schema, and an output schema for return values, the description is complete. It tells the agent what the tool returns, when to use it, when not to use it, and why it is distinct from sibling tools.

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 including defaults, enums, and the timezone caveat. The description adds only indirect context such as 'recent open tasks' and 'resolves by name,' but it does not need to compensate for schema gaps.

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 a snapshot of the current workspace' followed by the concrete contents: task counts per view, recent open tasks, and every project, label, team and member. It also differentiates itself from any separate list tool, so an agent knows exactly what this tool resolves.

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 says this is the tool for workspace discovery and resolving entities by name, notes there is no separate list tool, and instructs agents to use it for that purpose and not as a warm-up before every turn. This gives both a positive trigger and a clear exclusion.

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 specify readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by clarifying that this is a prerequisite reading step and describing the guide's scope. It does not mention return values, but an output schema exists and the operation is read-only.

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 core purpose is front-loaded in the first sentence, followed by a well-structured list of 11 topics with brief, concrete examples. The length is justified for disambiguating topics, and each entry is informative. It is slightly long but organized in a scannable format.

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 guide tool with complete schema coverage, explicit annotations, and an output schema, the description fully covers what the tool does, when to use it, and how to choose a topic. No critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by elaborating each topic enum value with concrete usage examples (e.g., 'bulk: Completing, moving, or editing more than one task at a time'), helping the agent choose the correct topic. The context parameter is not addressed in the description, but the schema already provides detailed instructions for it.

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

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

The description states a specific verb and resource: 'Read Done Bear's guide for one topic' and explains what the guide contains. It is clearly distinguished from all sibling tools, which are action-oriented operations (task_add, comment_edit, etc.), whereas this tool provides guidance rather than performing product work.

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 an explicit usage trigger: 'Load a topic before doing that kind of work for the first time in a session.' The topic list further maps each guide to concrete tasks, so the agent can decide when a guide is relevant. It does not explicitly state when not to use the tool or name alternatives, but no direct alternative exists among the 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=false and destructiveHint=false, so the description does not need to restate those. The phrase 'in the workspace' adds a small amount of context, but the description discloses no additional behavioral traits such as idempotency behavior, permission requirements, or 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 a single concise sentence with no filler or repetition. It immediately conveys the core operation without unnecessary detail.

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

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

For a simple create operation, the description combined with the rich input schema and output schema is largely complete. The only meaningful gap is the lack of guidance distinguishing label_create from label_add, which an agent may need when selecting the correct sibling tool.

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 parameters title, context, workspace, and idempotency_key are already fully documented. The description adds no parameter-level detail, which is acceptable given the schema's completeness.

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 ('Create'), the resource ('a new label'), and the scope ('in the workspace'). It distinguishes well from label_list and label_remove, but it does not explicitly differentiate from the similarly named sibling label_add.

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 no guidance about when to use this tool versus alternatives such as label_add, label_edit, or checklist_add. The intended context is implied by the name and description, but no explicit when-to-use or when-not-to-use information is provided.

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 mutable and destructive, so the description adds valuable action-level behavior: add creates, edit only changes provided fields, empty string clears description/target_date, and join/leave affect the caller's sidebar list. It does not cover all side effects such as permissions or irreversibility, but the annotations and schema lower that 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?

Three sentences carry the full behavioral contract without fluff. The main purpose is front-loaded, and the action-by-action breakdown is scannable and directly tied to the enum values in the schema.

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

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

For a 9-parameter tool with 100% schema coverage, an output schema, and annotations, the description covers the essential behavior an agent cannot infer from structured fields: per-action semantics, required parameters per action, and the read alternative. 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, but the description goes beyond the schema by clarifying action-specific parameter rules: name is required on add, project is needed for edit/join/leave, and empty strings have a clearing effect. This meaningfully helps an agent construct valid calls.

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: 'Create or change a project,' then enumerates exactly what each action does (add, edit, join, leave). It also differentiates from the sibling get_context by explicitly directing read operations 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 clear context for when to use each action and states that reads should be done with get_context. It does not explicitly compare against task_* or other siblings, but the resource boundary (project vs. tasks/attachments/comments) is evident enough.

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, so the description adds valuable behavioral context: ranked matching order (exact/prefix, then word-boundary/substring/fuzzy) and recency/status influence on results. It does not cover pagination behavior, but the cursor schema and output schema reduce that 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?

Three tight, front-loaded sentences. The first sentence states the core action and scope; the following two add high-value ranking behavior without repeating schema details. 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?

For a read-only search tool with a detailed schema and output schema, the description supplies the key behavioral nuances an agent needs: matching semantics, ranking order, recency/status factors, and multi-word treatment. 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 description adds meaningful semantics for the query parameter by explaining ranking tiers and multi-word matching order, and clarifies workspace scope. It does not elaborate on limit/state/cursor/timezone, 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 uses a specific verb and resource ('Search tasks across the workspace') and details the lexical matching scope over title and description. It clearly conveys what the tool does, though it does not explicitly distinguish it from sibling tools like task_list or task_show.

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 implies the tool is for finding tasks by text query across the workspace and provides query-behavior details, but it never states when to prefer search over task_list/task_show or when not to use it. There are no explicit alternatives or exclusions.

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

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

The description reveals important behavioral details beyond the annotations: new tasks land in Today by default, the default is timezone-dependent, and checklist order is preserved. Since the annotations only provide basic false hints for read-only/open-world/destructive flags, the description carries the transparency burden and largely succeeds, though it does not mention authorization requirements or broader 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, starting with the core operation before addressing the highest-risk semantics. Every sentence carries useful information, and there is no filler or repetition of schema details that are already fully stated.

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

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

For a 13-parameter creation tool, the description covers the non-obvious behavioral details an agent would need: default GTD bucket, timezone handling, date format, and checklist creation semantics. The schema fully documents the remaining parameters, and the output schema covers return values, leaving no material gap 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, and the description adds meaningful extra semantics: what 'when' values mean, the interaction between the default and timezone, YYYY-MM-DD date formatting, and the guarantee that checklist order is preserved. These nuances go beyond the schema's property descriptions without needing to restate every 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?

The description opens with a specific verb and resource: 'Create a new task.' It goes beyond the generic title by explaining the tool's scope around GTD views, checklist creation, labels, and assignees, which clearly distinguishes it from task_edit, task_assign, task_list, and other 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?

It gives clear contextual guidance for when to use the tool, such as passing 'when: inbox' for an uncommitted capture and always including the user's timezone to avoid UTC misclassification. It also advises passing sub-items as checklist items in one call, but it does not explicitly state when to prefer task_edit or other alternatives for modifying existing tasks.

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 destructiveHint=true, so the description's added value is explaining the concrete effect: tasks are moved to the Trash view and removed from all working lists. This goes beyond the annotation and sets accurate expectations about the operation's impact.

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 deliver the core action, batch behavior, consequence, and user-confirmation requirement without redundancy or filler. The most important safety instruction is positioned at the end but remains prominent.

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 for a destructive batch operation: it states what happens, the max batch size, and the confirmation requirement. The output schema and annotations cover the remaining details, though the description could have explicitly tied the task selector parameters to the archived task(s).

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 parameter explanations are already fully present. The description reinforces `tasks` and the 50-item cap, but it does not add meaning beyond what the schema already states.

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

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

The description uses a specific verb and resource: 'Archive a task, or several at once with `tasks`'. It also defines the outcome clearly ('move to the Trash view, out of every working list'), which distinguishes it from siblings like task_done or task_reopen.

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

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

The description gives clear usage context, including the batch limit and a critical user-confirmation requirement: 'Confirm with the user first.' It does not explicitly name alternatives or when not to use this tool, but the guidance is sufficient for correct invocation.

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?

The description richly discloses behavior beyond annotations: patch semantics ('Only the provided fields are changed; omitted fields are left untouched'), notes replacing rather than appending, assignee clearing, and batch irreversibility ('cannot be undone in one call'). None of this contradicts the idempotentHint or destructiveHint 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 paragraph is dense but every sentence earns its place: target scope, patch semantics, clearing, notes behavior, assignment, labels, and batch caution. The core operation is front-loaded with 'Update fields on one task...' and no filler or redundant re-statements of the tool name.

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 15 parameters, full schema coverage, an output schema, and annotations, the description is complete enough for correct invocation. It covers the essential behavioral semantics, batch limits, and user-confirmation requirement. The implied precondition that `task` or `tasks` must identify the targets is clear from the opening sentence.

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 meaningful cross-parameter semantics: `clear` is the mechanism for removing values, `notes` replaces existing content, `assignee` can be cleared, and `add_labels`/`remove_labels` modify label membership. This goes beyond the individual schema 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?

States a concrete operation: 'Update fields on one task (`task`) or on several at once (`tasks`, max 50).' The verb-resource pairing is specific and clearly an edit/update tool versus siblings like task_add or task_done. It does not explicitly name or contrast sibling alternatives, so it stops short of full 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?

Provides clear context for when to use the tool: partial field updates, clearing values via `clear`, replacing notes, assigning/unassigning, and modifying labels. It also gives an important usage condition for batch edits: 'confirm the list with the user first.' It does not explicitly state when-not-to-use or name sibling tools like task_done, so it lacks 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 mark the call read-only and non-destructive; the description adds substantial behavioral detail beyond that: sort order, completed-task ordering, view/state precedence, and hasMore pagination semantics. 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?

Four dense sentences front-load the core behavior, and every clause contributes: ordering, filters, search ranking, view/state override, and pagination. The enum list repetition is acceptable because it saves the agent from reopening the schema.

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

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

For an 8-parameter tool with a full output schema and read-only annotations, the description covers the essential behaviors an agent needs to call it correctly: ordering, filter semantics, search behavior, view/state precedence, and pagination results. Remaining parameters are fully 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 coverage is 100%, so the baseline is 3. The description earns a 4 by adding meaning beyond the schema: it clarifies that logbook/trash views read completed/archived tasks regardless of state, and that search ranks within the current filter.

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

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

The description clearly identifies the operation and scope: 'List tasks in the workspace' with explicit ordering and filtering behavior. It does not explicitly differentiate task_list from sibling tools like task_show or search, so it falls short of a 5.

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

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

Provides concrete usage context: how view and state filters interact, and that logbook/trash override state. It does not name alternatives or state when-not-to-use conditions, so explicit routing guidance is missing.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description reveals meaningful behavioral details: include sections are optional because they cost extra reads, comments arrive oldest first with author and edit status, and attachments come with short-lived signed URLs. This helps the agent predict resource costs and interpret returned 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?

Two tight sentences with no filler. The main purpose is front-loaded, and the second sentence earns its place by explaining costly optional behavior. Every phrase adds signal.

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

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

Given a rich output schema, read-only annotations, and a clear optional-include design, the description covers what an agent needs to invoke correctly: what is returned, how to select a single task, and which sections add extra reads. The timezone and workspace details are already fully handled by the schema, so the description does not need to repeat them.

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 five parameters at 100% coverage, so the baseline is 3. The description adds extra semantic value to the include parameter by explaining exactly what 'comments' and 'attachments' yield and their behavioral traits. It also reinforces that the task parameter is a workspace-scoped number.

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: 'Get full details for a single task: its fields, labels and checklist items.' This clearly distinguishes task_show from sibling tools like task_list (multiple tasks) and task_edit (modifying), and the workspace-scoped task number pinpoints exactly which task is addressed.

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

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

The description makes the tool's intended use clear: it is for retrieving one task's full details. It also gives strong guidance on when to add the optional include array, noting that comments and attachments 'cost extra reads' and should only be requested when needed. It does not explicitly name alternatives or say 'use task_edit to modify,' so it stops short of full exclusions.

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