Decknote

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

Annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot convey: per-file and per-board size quotas that vary by plan (Free vs Pro) and server-side photo optimization. It does not mention failure behavior when limits are exceeded, which is the one notable gap.

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 core action before the quota detail, and every clause carries information. 'Photos are optimized, as in the app' is mildly informal filler but still communicates a real side effect, 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 mutation tool with no output schema, the description covers input modes, size constraints and transformation behavior, while annotations cover the destructive/read-only profile. What is missing is error/limit-exceeded behavior and any permission requirement, which would be the remaining useful additions.

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 67%, so roughly a third of parameters are undocumented in the schema. The description compensates by explaining the pairing semantics — url for links, contentBase64 + filename for files — which the schema lists as independent properties without stating they are alternatives. Undescribed parameters (mimeType, name) remain slightly ambiguous, but the mode distinction is the critical semantic.

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 (attaches) and resource (link or file) and names the target object (a task), so an agent immediately knows what the tool produces. It also distinguishes the two input modes, url vs. contentBase64 + filename, which is the key ambiguity for this tool. The verb 'add_attachment' is unambiguous against siblings like delete_attachment and rename_attachment despite no explicit naming of them.

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 usage by mapping each mode to its parameters (link via url, file via contentBase64 + filename), which tells the agent how to pick a path. However, it never states when to prefer this over sibling alternatives such as create_embed or add_comment, nor any prerequisites (e.g., board membership or permissions). Usage is inferable but not stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write nature is covered. The description usefully clarifies that existing checklists are preserved, which is additive-behavior context beyond the annotations, but it says nothing about permissions, limits, or effects on the task's state.

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

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

A single front-loaded sentence with no padding. It is efficient, though brevity here comes partly from omitting 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?

Three parameters, low schema coverage, no output schema, and no annotations about the target card. The description omits what cardId refers to and what items should look like, leaving the definition too thin 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 only 33% (only title is documented), and the description does not compensate: it never explains cardId, the items array format, or how checklists are titled. 'with its items' vaguely alludes to the items parameter but adds no usable syntax.

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?

Clear verb+resource: adds a checklist to a task, and it distinguishes itself somewhat by noting items are included and that it does not replace existing checklists. It never explicitly contrasts with the close sibling add_checklist_items, which handles adding items to an existing checklist, so an agent must infer the boundary.

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?

There is no explicit when-to-use guidance and no named alternative, despite the presence of add_checklist_items, update_checklist, and delete_checklist. The clause 'in addition to its other checklists' hints at scope but is not a routing rule.

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, destructiveHint=true, and openWorldHint=false, so the mutation/safety profile is covered. The description usefully adds the append-at-end placement semantics, but says nothing about idempotency, duplicate handling, item format, or what happens to existing items.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably under-specified rather than optimally concise.

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?

Annotations cover the safety profile and there is no output schema to explain. Still, for a two-required-parameter mutation with 0% schema coverage, the description omits item format, multi-item behavior, and error/ordering semantics, leaving real gaps.

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

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

Schema description coverage is 0% and there are two required parameters, so the description carries the full burden. It does not explain that 'items' is an array of plain strings (item text) or what 'checklistId' must reference, leaving both parameters' meaning to the bare schema types.

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

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

The description states a specific verb+resource ('Adds items') and adds scope detail ('at the end of a checklist'), which distinguishes it from add_checklist (creates a checklist) and update_checklist_item. However, it does not explicitly name or contrast those siblings, so the agent must infer the routing.

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

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

Usage is implied: use it when appending items to an existing checklist. There is no explicit when-to-use vs update_checklist_item/add_checklist guidance and no stated prerequisites (e.g., checklist must exist, permissions).

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

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

Annotations mark it as destructive and not read-only, and the description adds crucial context: notify defaults to false, confirm:true is required for notification, and without confirm the result is a preview. This is valuable behavioral detail beyond annotations. It doesn't explain what 'destructive' means here or what access is required.

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 the core action, then default behavior, then the notify/confirm interaction. No wasted words. Could be slightly tighter, but every sentence adds value.

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

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

Given no output schema and 4 parameters with 75% schema coverage, the description covers the main behavioral caveats (notify + confirm) and default. It doesn't mention return values or error cases, but for a comment-adding tool, this is reasonably complete.

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 75%, and the description explains the interaction between notify and confirm: notify:true needs confirm:true, otherwise a preview is returned. This adds meaning beyond the schema, which individually describes each parameter but not their joint behavior. The text parameter's @mention syntax is only in the schema, not the description.

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

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

The description states a specific verb and resource ('Adds a comment to a task') and adds the actor ('as the user'). It does not explicitly distinguish itself from siblings like edit_comment or delete_comment, though 'adds' implies creation rather than modification.

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 clarifies the default behavior (nobody notified) and what notify:true does, with a clear condition for using it. But it doesn't mention when to use this instead of edit_comment or react_to_comment, and doesn't explain required permissions or prerequisites.

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 adds substantial behavioral context beyond the annotations: accepted formats, base64 plus filename delivery, authorization rules, the 10-per-expense limit, and plan-based size caps. It does not explain the destructiveHint=true implication, such as whether the addition modifies or replaces existing receipt state or how it can be undone.

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: attachment behavior comes first, followed by permissions and limits. Every sentence contributes operational detail without repetition.

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

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

Given the three required parameters, annotations, and lack of an output schema, the description supplies enough context to invoke the tool correctly. It covers formats, encoding, authorization, per-expense count limits, and size caps.

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 parameter meaning is already largely documented. The description still adds useful semantics: accepted file types, the base64-encoded file plus filename convention, and file-size constraints that apply to the content 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 states a specific verb and resource: attaches a receipt to an expense. It immediately distinguishes the operation from general attachment or expense-creation siblings by naming the exact target and supported receipt formats.

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 clearly states who may use the tool and that receipts can also be added to expenses already on an invoice. It does not explicitly name when to use this instead of add_attachment or delete_expense_receipt, so alternative routing is only 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?

The description adds substantial behavior beyond the annotations: it explains the capacity impact across the Workload, the weekend no-op behavior, the one-per-day constraint, and the Pro-plan requirement. This is exactly the kind of side-effect disclosure needed for a mutation tool.

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

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

The description is front-loaded with purpose and scope, then immediately explains behavioral consequences. It is dense but every sentence carries relevant information.

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

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

For a two-parameter mutation tool with annotations and no output schema, the description covers purpose, side effects, constraints, plan gating, and edge cases like weekends. An agent has enough context to call 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 coverage is already 100%, so the baseline is 3. The description adds useful meaning by explaining the effect of the 'day' parameter on weekly capacity and the weekend exception, plus it reinforces the 80-character name constraint.

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

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

The description states a specific verb and resource: adding a holiday to the user's calendar. It also scopes the operation by explaining that it applies to everyone in the Workload, which distinguishes it from personal time-off operations.

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 usage context: holidays affect everyone's weekly capacity, and holidays on Saturdays or Sundays change nothing. It also notes that this is a Pro feature, though it does not explicitly compare against siblings like add_time_off or list_holidays.

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=true, but the description adds genuinely new behavioral facts: plain-text-only input, a 5000-character ceiling, the side effect that the page moves up its list, the archived-page restriction, and the required editor role. That is unusually strong disclosure of auth, limits, and side effects for a mutation tool.

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

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

One sentence, front-loaded with verb and resource, with constraints appended in a tight semicolon-separated chain. 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?

Without an output schema, the description is largely self-sufficient: input medium, limit, side effect, permissions, and the archived-page constraint are all present. It omits what the call returns and whether the comment triggers notifications, which are minor but real gaps for a 2-param mutation.

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% — both pageId and text are already described in the schema, including the 5000-character limit repeated here. The description adds no syntax, format, or ID-sourcing detail beyond the schema, 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+resource ('Adds a comment') and scopes the target as 'a note or discussion', which distinguishes it from the sibling add_comment / edit_page_comment family. It does not explicitly name those siblings or explain the task-comment vs page-comment split, 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?

Gives two real preconditions — not usable on an archived page, and requires the editor role on the project — which is clear context for when the call will succeed. It stops short of naming an alternative tool to use instead (e.g. add_comment for tasks) or what to do when the page is archived.

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 real side effects: a push notification and an email are dispatched, and relative reminders track the due date and repeat with repeating tasks. This is meaningful behavior an agent could not infer from readOnlyHint=false / destructiveHint=true / openWorldHint=false alone.

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 action and its effects, then the scheduling semantics, with no filler sentences. The second clause is dense and slightly run-on, but every element carries information the 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?

For a 5-parameter mutation tool with no output schema, the description covers effects and both scheduling modes well, and the annotations carry the safety profile. It could still note the required `cardId` explicitly and mention whether the reminder is immediately active or error behavior.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: `at` is defined as an ISO 8601 instant, `timeZone` as IANA, and `daysBefore` + `time` as a due-date-relative offset. Only `cardId` is left implicit via the phrase 'on a task', which is a minor gap.

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

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

States a specific verb and resource ('Adds a reminder for the user on a task') plus the concrete effect (push notification and email), which cleanly separates it from list_reminders and remove_reminder among the 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 effectively explains the two mutually exclusive ways to schedule the reminder ('Either `at` ... or relative to the due date'), which tells the agent which parameter set to choose. It stops short of stating when to prefer this tool over list_reminders/remove_reminder or any prerequisite conditions.

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 annotations (which only flag it as a non-read-only, destructive write in a closed world) it discloses the approval/pending state, that owners get a notification, that approved time lowers capacity in Workload for Mon–Fri weeks touched, the 366-day cap, and that the note is refused when the time off is for somebody else. That is substantial side-effect and authorization context an agent could not infer from structured fields.

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 actor and resource before the conditional rules, and every clause carries information (kinds, span, capacity effect, approval logic, note ownership). It is a single dense paragraph of long semicolon-joined sentences, which is harder to parse than it needs to be, but nothing is filler.

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

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

For a mutating, multi-actor tool with no output schema, the description covers the outcomes an agent must anticipate: resulting approval status, notification side effect, capacity change, span limit, and the note-permission failure mode. Nothing material for correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, and the description adds real semantics on top: the note is private to the subject and refused when recording for another person, and a single day applies when no last day is given. It does not add detail on minutesPerDay or userId beyond what the schema already says.

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 (records time off), the two actors it can act on (the user, or on Pro an editor of a project the user owns), and the accepted kinds and date span. It is clearly distinguishable from siblings like approve_time_off, update_time_off, list_time_off and remove_time_off.

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 conditions: own time off becomes a pending request when an owner of an edited project plans with the team calendar, otherwise approved at once, while time off for an editor is approved immediately. It also states constraints (366-day maximum, note only writable by the subject) but does not name the sibling to use when correcting or cancelling an existing entry.

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 adds substantial behavior beyond the annotations: confirm:true is required or nothing is sent and a preview is returned, responses have secrets removed, and only specific endpoint families are reachable. These details materially affect how an agent must invoke the tool and are not available from the structured annotations alone.

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

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

The description is dense but front-loads the core operation and then groups route-specific details compactly. It could be more scannable with bullets, but nearly every sentence carries necessary constraint or body-shape information.

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

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

For a generic, multi-endpoint create tool, the description covers reachable routes, required confirmation, authentication behavior, and response sanitization. It does not describe the successful return shape when confirm:true is passed, and there is no output schema to cover that gap.

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

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

Although schema coverage is 100%, the nested body parameter is only described as 'The JSON body the route documents.' The description compensates by enumerating the supported body shapes for each reachable route and clarifying that path must be a Decknote-relative path, not a full URL.

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 operation (create via POST) and enumerates the exact reachable resource routes: boards, cards, and board embeds. It is clear enough to distinguish this as a generic API-create tool, but it does not explicitly differentiate itself from sibling high-level creators like create_board, create_task, or create_embed.

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 provides implicit when-to-use guidance by listing the reachable routes and constraints, such as authentication and internal endpoints being unavailable. However, it never states when an agent should choose this generic API tool over the dedicated create_board, create_task, or create_embed siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent ('it doesn't change anything'). It adds real value beyond the annotations: the reachable-endpoint whitelist, the exclusion of sensitive endpoint classes, and the note that secrets are stripped from responses. It does not describe pagination or output size limits for the bulk /api/export case.

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 operation and its read-only nature, then a compact endpoint inventory that earns its space by enumerating exactly what is callable. The endpoint list is dense but each entry adds a distinct capability; the prose is not padded with 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?

There is no output schema, so the description compensates by sketching return shapes per endpoint (user id/name/email, board lists, embed list, link-preview title/description, attachment type/size). Combined with the reachability and auth constraints, an agent has enough to call it correctly; only response volume/pagination for the export endpoint is left unstated.

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 path must be a Decknote-relative path, not a full URL, and the query object carries optional string/number/boolean parameters. That exceeds what the schema's field descriptions convey.

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 ('Reads from Decknote's HTTP API ... with GET') and immediately scopes it as read-only. It also distinguishes itself from the 70+ dedicated siblings by declaring it 'covers what no dedicated tool returns,' with concrete examples (uploaded text file contents, link previews). An agent can tell what this tool is for without opening the schema.

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

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

Gives clear context for use: only for data no dedicated tool returns, with examples of such cases. It also supplies a when-not list (authentication, token, session, admin, payment and internal endpoints are not reachable). It does not name specific sibling tools to prefer for the common endpoints it lists (e.g. boards), so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=true. The description adds valuable context beyond annotations: approval lowers the person's capacity in Workload, triggers a notification, requires confirm=true, and otherwise returns a preview. It does not discuss reversibility, but this is not contradictory.

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 action and appropriately short. Its three sentences each add useful information about effects, Pro-feature context, and confirm behavior. The first sentence is slightly tangled but still concise.

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 approval mutation with no output schema, the description covers the key effects and the preview behavior when confirm is omitted. It does not mention the note parameter or describe what a confirmed response looks like, but the essential behavioral context is present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the confirm=true vs preview behavior, but adds no meaning beyond the schema for timeOffId or note. 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?

States a specific verb and resource: approves a time off request from an editor on a project the user owns. The effect on capacity and notifications is clear, but it does not explicitly distinguish itself from siblings such as reject_time_off or approve_timesheet.

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

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

Provides a prerequisite for execution: confirm must be true or the result is only a preview. It also notes this is a Pro feature. However, it does not explicitly say when to choose this over reject_time_off or other time-off tools.

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

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

Annotations only say destructiveHint=true and readOnlyHint=false; the description adds the real consequences: hours are locked for the submitter, the project owner retains edit rights, a notification is sent, and without confirm nothing changes but a preview is returned. This is exactly the behavioral context annotations cannot 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?

The core action and its consequences are front-loaded, and each sentence carries information. The first sentence is somewhat long and packs several facts (lock, owner override, notification), but nothing is wasted.

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 three-parameter mutation with no output schema, the description covers preconditions, consequences, the confirm gating rule, and the Pro-tier requirement. An agent has everything needed to call 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 coverage is 100%, so the baseline is 3. The description goes beyond it by explaining what the preview from a missing confirm contains ('the week's hours by project and task') and by tying note to the notification, adding usage meaning the schema doesn't.

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 ('Approves a week of hours') and clarifies the scope: a submission by a person on the user's projects. This clearly distinguishes it from reject_timesheet, submit_timesheet, and withdraw_timesheet in the sibling list.

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 concrete precondition ('A rejected week has to be submitted again first') and an operational rule for the confirm flag (preview without it). It does not explicitly name a sibling alternative such as reject_timesheet, so it falls just short of a 5.

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

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

Annotations already flag destructiveHint=true, but the description adds context the annotations cannot: the board disappears from everyone's dashboards (multi-user impact), the data survives until restored (partial reversibility), the user must own the board, and it doesn't count against the free-plan cap. It does not say who can restore it or whether the action can be undone in-app.

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, no filler, and the core effect (leaves dashboards, data retained) is front-loaded before the secondary plan-limit 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 one-parameter, no-output-schema tool, the description covers the user-visible consequences: dashboard removal for all members, data retention, ownership requirement, and plan implications. Only the boardId format and the restore path are left implicit, which are minor for this complexity.

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

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

Schema description coverage is 0% and the sole parameter boardId gets no mention or format guidance in the description. The parameter is largely self-evident by name, so the description neither compensates for nor worsens the gap; a baseline 3 is appropriate for a single obvious identifier.

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

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

States a specific verb (archives) and resource (a board), plus the ownership precondition. The clause 'keeps all its data until it is restored' implicitly separates it from delete_board and points at restore_board, so an agent can distinguish it from siblings without opening their 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?

Gives clear context for when this is the right action: you want the board off everyone's dashboard but not gone, and archiving has a plan-limit benefit. It never explicitly names restore_board as the undo path or states when archiving would be wrong, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial context beyond them: the side effects on the plan's client limit, the fact that projects retain the link and time is preserved, and the two-phase preview/commit behavior. This is exactly the kind of behavioral detail that earns a top score even when annotations are present.

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 clauses with zero filler. The core action is front-loaded, the effects follow immediately, and the confirm requirement is stated last where it functions as the pre-call checklist item.

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 mutation tool with no output schema, the description covers everything an agent needs: what changes, what is preserved, and the mandatory confirm flag that prevents an accidental commit. Nothing material is left unstated.

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

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

Schema coverage is 50%: confirm is already fully documented in the schema, and the description essentially restates its preview semantics rather than adding new meaning, while clientId carries no description in either place. Schema does the heavy lifting for the one documented parameter, so a baseline 3 is appropriate.

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

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

The description states a specific verb and resource ("Archives a client") and then goes further, explaining the concrete effects: it leaves the active list, stops counting toward the plan's client limit, keeps project links, and preserves time. A sibling restore_client exists, and while the description never names it, the action itself is unambiguous.

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

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

Usage is implied through the archiving semantics (the client leaves the active list) and the confirm gate, but there is no explicit when-to-use guidance or comparison against the obvious alternative, restore_client, or delete-style operations. An agent must infer the trigger condition from context.

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?

Adds real context beyond the annotations: data is preserved, the task is restorable from the archive, and archiving a dated repeating task spawns its next occurrence. That side effect is non-obvious and not derivable from destructiveHint=false/true alone. It stops short of stating permissions or failure behavior.

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

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

Two tight sentences, front-loaded with the core action and then the non-obvious repeat-task side effect. No filler.

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

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

With annotations covering the mutation safety profile and no output schema, the description supplies the key behavioral facts an agent needs (recoverability, side effects). It is only slightly short on authorization/error context, which is a minor gap for a one-parameter 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 coverage is 0%, so the sole required parameter (cardId) is documented only by its name in the schema. The description says 'a task' but never clarifies identification, so it adds essentially no semantic value over the schema field itself.

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 ('Archives a task') and immediately defines the semantics: the card leaves the board but retains data and can be restored. This implicitly distinguishes it from delete_task (permanent) and pairs with restore_task, so an agent can pick correctly without opening the schema.

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

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

The behavior described makes the use case inferable (remove from board without destroying), but no explicit when-to-use, when-not-to-use, or named alternative (delete_task vs archive_task) is given. Usage is implied rather than stated.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, openWorldHint=false. The description adds value beyond that: the 100-task cap, the single-board scope, and notably that archiving repeating tasks creates their next occurrence — a non-obvious side effect not captured by annotations.

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

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

A single front-loaded sentence that covers scope, actions, and the key side effect. Efficient, though cramming the repeating-task behavior into a parenthetical slightly buries it.

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 4-param mutation tool with no output schema, the description covers scope, the action-to-parameter mapping, and an important side effect. It omits error/permission behavior and what happens to individual task results, but is largely complete for safe 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 50%; listId and labelId have schema descriptions, and the enum for action is machine-readable. The description ties each action to its parameter via examples, but adds no format/syntax detail beyond what the schema already documents.

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: acts on up to 100 tasks of one board at once, enumerating the three actions (move, add_label, archive). The 'multi-select in the app' analogy and the batch scope clearly distinguish it from single-task siblings like move_task, set_task_labels, and archive_task.

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

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

The description implies when to use it (batch operations on many tasks at once) but never explicitly contrasts it with the single-task siblings it overlaps with. It doesn't state prerequisites (e.g., all cardIds must belong to one board, matching the 'one board' constraint) or when to prefer the individual tools.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/mutating nature is covered structurally. The description adds only that the resulting state is 'completed (done)'; it omits whether the change is reversible (reopen_task exists), what happens to subtasks/checklists, and any permission requirements.

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 short sentence with the action front-loaded and no filler. It is appropriately sized, though its brevity is partly the source of the missing context.

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 state-mutating tool with no output schema and an undocumented required parameter, the description leaves out permissions, reversibility, and side effects on related items. Annotations cover the safety profile, but the definition is still too thin to call the tool confidently.

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

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

Schema description coverage is 0% — the single required parameter cardId is a bare string with no explanation. The description does not identify what cardId refers to (a task card identifier) or its expected format, so it fails to compensate for the schema gap.

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

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

The description states a specific verb ('Marks') and resource ('a task'), and clarifies the resulting state ('completed (done)'). It stops short of distinguishing itself from closely related siblings such as reopen_task, archive_task, or update_task, which an agent must infer.

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?

There is no guidance on when to use this rather than reopen_task (the inverse), archive_task, or update_task, nor any stated prerequisite such as the task existing or the caller having board membership. Usage must be inferred entirely from the name.

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?

Adds useful behavior beyond annotations: the resulting invoice is a draft with the same lines, the conversion has a one-time constraint tied to invoice lifecycle, and it counts toward the free plan document quota. It does not describe permissions or whether the estimate is marked consumed, but the annotations already flag destructive behavior.

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

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

Front-loads the core action and result, then adds lifecycle and quota constraints compactly. No wasted sentences.

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 one-parameter conversion with no output schema, the description covers the action, result, one-time lifecycle constraint, and billing impact. Minor gaps remain around exactly what is returned or whether the source estimate is altered, but the essentials are present.

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

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

Schema coverage is 100%, so the single parameter is already documented. The description reinforces that the input is an accepted estimate but adds no format or identity details beyond 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: turning an accepted estimate into a draft invoice with the same lines. This is clearly distinct from generic invoice creation siblings such as create_invoice and create_invoice_from_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?

Explains the lifecycle condition: it can be done once while the resulting invoice stands, and again only after the invoice is voided or its draft deleted. It does not explicitly compare against sibling tools like create_invoice_from_work, but the accepted-estimate condition provides clear selection context.

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

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

Annotations already flag this as a non-read-only, destructive mutation; the description adds important behavior beyond that: budget derivation, hourly-rate propagation, task generation, re-linking the estimate, and board-limit consumption. It still does not explicitly state irreversibility or what exactly is lost/changed from a safety standpoint.

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

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

The description is front-loaded and contains no filler; every clause carries operational meaning. However, it is a single dense sentence with several nested conditions, which reduces readability for such a side-effecting conversion operation.

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 four-parameter conversion tool with no output schema, the description covers prerequisites, budget behavior, task creation, derived hourly rate, estimate re-linking, and plan limits. It omits return shape and explicit failure conditions, but the core invocation context is complete.

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 75%, and the description meaningfully compensates for the undocumented budget enum by defining the money/hours/none outcomes. It also explains the tasks toggle and default task behavior, though title semantics are mostly already present 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 and result ('Makes a project board from an accepted estimate') and sharply scopes the input ('not tied to a project yet'). It clearly separates this operation from siblings like create_project and convert_estimate_to_invoice.

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 the prerequisite condition clearly: the estimate must be accepted and not already tied to a project. It does not explicitly name when to choose convert_estimate_to_invoice or create_project instead, so the alternative routing is left implicit.

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 destructiveHint=true, readOnlyHint=false, so the mutation profile is known. The description adds real context beyond that: the one-rule-per-board free-plan limit, and it discloses that creating a rule has ongoing side effects. It does not mention permissions or that the rule executes asynchronously in the future, but it exceeds the annotation baseline.

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 capability, then the trigger taxonomy, then action taxonomy, then the plan limit. Every clause carries a required-field mapping or a constraint; no filler.

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

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

For an 11-param tool with 0% schema coverage and no output schema, the description supplies the conditional-requirement graph that the schema lacks. It stops short of stating boardId/name semantics and creation preconditions, but no critical field mapping 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 0%, so the description carries the full burden and does so cleanly: it maps each trigger to its required id field and each action to its required companion field (actionListId, actionLabelId, actionUserId, actionDays, actionText). This is exactly the conditional parameter semantics the schema cannot express.

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 ('Adds a board rule') and fully enumerates the WHEN/THEN grammar available. An agent can distinguish this from delete_automation and set_automation_enabled without opening the schema.

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

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

It implies creation but never states when to use this versus alternatives, nor that a rule must be deleted rather than edited. The 'Free plan: 1 per board' constraint is the only boundary guidance, which is useful but incomplete.

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, destructiveHint=true, openWorldHint=false, so the safety profile is covered. The description goes beyond them usefully by disclosing the return payload ('returns the board with its list ids') and a hard quota constraint ('free plan allows 5 owned boards'), which is exactly the kind of operational limit 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?

Four short sentences, front-loaded with the core action and followed by parameter behavior, return value, and quota. Dense but every sentence carries information; the only minor cost is the semicolon-heavy mid-section that packs template semantics into one line.

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

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

With no output schema, the description compensates by describing the return value, and it covers the quota constraint. Remaining gaps are small: ownership/permission nuances and what happens if the free-plan limit is reached are not stated, but nothing essential to invoking the tool 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 67% (title is undocumented but self-evident). The description earns its place by explaining what each template value actually yields ('blank (To do / In progress / Done), kanban, content or personal'), that it is localized to the user's language, and that `lists` overrides the template's lists while keeping its labels — real semantics beyond the enum and the schema text.

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 (creates a board) and immediately scopes it with ownership ('owned by the user') plus what the two optional parameters produce. It does not explicitly differentiate itself from nearby siblings like duplicate_board or import_trello_board, which is the only thing keeping it from 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?

Usage is implied rather than stated: you call it when you want a brand-new board. There is no when-not guidance and no mention of the obvious alternatives (duplicate_board, import_trello_board) that an agent should be choosing between when a board already exists elsewhere.

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 cover the safety profile (readOnly=false, destructive=true, openWorld=false), so the bar is lower, and the description still adds substantive behavior: project linkage, propagation of currency and hourly rate to the client's time, and a plan-limit constraint. It doesn't state whether the operation is reversible or what happens when the free-plan limit is hit, so it falls short of a 5.

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

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

Three short sentences, front-loaded with the core action, then useful domain context, then the quota caveat. No filler, though the linkage sentence and the rate sentence could be merged without loss.

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 mutation tool with no output schema, the description covers the domain model and a quota constraint but omits what a successful call returns (e.g., the new client identifier) and whether any parameters are required. It is adequate but leaves meaningful gaps for an agent composing the call.

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 63%, so roughly a third of the 8 parameters (notes, phone, address, and partially others) carry no documentation anywhere. The description adds domain meaning for currency and hourlyRate by explaining how they propagate to projects and time, but leaves the remaining parameters to the schema. 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?

"Adds a client" is a specific verb+resource, and the following sentences clarify what a client is in this domain (linked to projects, carries currency and hourly rate). It doesn't explicitly distinguish itself from siblings like update_client or archive_client, but the resource naming is unambiguous enough for selection.

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 a real precondition — the free plan allows only 2 active clients — which tells the agent when this call may fail or be inappropriate. However, it names no alternative (update_client, restore_client) and states no when-to-use vs. when-not-to-use rules beyond the quota.

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, destructiveHint=true and openWorldHint=false, so the agent knows this is a mutating, non-open-world call. The description adds the plan quota, a genuine constraint not present in annotations, but it never explains what makes the operation 'destructive' or what permissions are needed. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Two short sentences, zero filler, with the core action and supported types front-loaded and the quota caveat trailing. Every clause earns its place.

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

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

For a 4-parameter mutation tool with no output schema and low schema coverage, the description covers what can be created but not what is returned (e.g., the new field's ID), permission requirements, or behavior on cards that already have the field. An agent could call it correctly but would be guessing at the response and side effects.

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

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

Schema description coverage is only 25% – just the 'options' parameter is documented, and boardId/name are bare. The description partially compensates by restating the type enum values and the 'up to 20 options' constraint, but adds nothing about boardId or name semantics, leaving half the meaningful parameters undocumented.

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 ('Adds a custom field to a board's cards') and enumerates the five supported field types, which lets an agent separate it from siblings like create_label or create_list without opening the schema. It does not explicitly name an alternative, but the field-type enumeration does the differentiating 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?

There is no guidance on when to use this versus update_custom_field or the other create_* siblings, and no prerequisites or when-not conditions. The free-plan quota ('3 per board') is a useful constraint but is a limit, not usage guidance.

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

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

Annotations declare the safety profile (readOnly=false, destructive=true, openWorld=true), and the description adds substantial context beyond them: plan/ownership auth requirements, the read-only-unless-canEdit access model, the external-server session flow, and critically the confirm:true gate with preview-by-default behavior. This is exactly the behavioral detail an agent needs before calling a mutation that exposes a board externally.

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

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

Three dense sentences that front-load the purpose before the constraints and the confirm gate. The parentheticals are information-packed rather than wasteful, though the second and third sentences are slightly run-on.

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

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

For a mutation tool with no output schema and partial schema coverage, the description covers what is created, who may create it, the access model, the dry-run gate, and the downstream session flow. Nothing an agent needs to invoke it safely 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 60%; the description adds meaning for canEdit ('read-only unless canEdit') and restates the origins cap, complementing the schema's own descriptions of confirm and origins. The name and boardId parameters remain unexplained in both places, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource ('show this board in an iframe' via an embed) and names the exact mechanism, distinguishing it from sibling list_embeds and revoke_embed. The parenthetical constraints (Pro, owner only) sharpen rather than obscure the purpose.

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

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

Gives clear preconditions for use: Pro plan, board owner, and an external app whose server will request a session via the REST API. It does not explicitly name alternatives (e.g. revoke_embed for teardown), but the context is strong enough to select the tool correctly.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds real context beyond them: permission requirements, the owner-only markup restriction, and the clarification that nothing is paid. It does not, however, explain the somewhat surprising destructiveHint=true for a create operation or any side effects on billing aggregation.

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 front-loaded sentences: purpose first, then the cost-vs-payment scope clarification, then permission constraints. It is efficient, though the field enumeration in sentence one partly duplicates what the schema exposes.

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

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

For a 9-parameter mutation tool with no output schema, the description covers purpose, field meaning, defaults implied by schema, and role requirements adequately. A brief note on the returned identifier or validation behavior would be the only meaningful addition.

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 78%, so most parameters (day, amount, cardId, billable, markupPercent, database description) are already documented in the schema. The description largely re-lists the same fields and repeats the enum values already present in the schema, adding only marginal narrowing value.

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

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

The description names a specific verb and resource ('Logs an expense on a project') and enumerates exactly what the expense captures, so an agent can distinguish it from siblings like create_invoice, log_time, or create_task without opening schemas. The scope note 'It records a cost; nothing is paid' further sharpens the intent.

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

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

It states concrete prerequisites and constraints — 'Needs the editor role on the project' and 'Only the project owner can set a markup' — which tell the agent when it can and cannot use the tool. It does not name sibling alternatives (e.g. delete_expense, update_expense, create_invoice), 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.

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description adds genuinely non-obvious behavior: the draft is private, numbering happens only on send, voided documents still consume the free-plan quota, and Pro is unlimited. That is meaningful context beyond the annotations, though it does not explain why a creation tool is flagged destructive (quota consumption) nor what the response contains.

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?

Six short sentences, front-loaded with what is created and what it copies, followed by the privacy/numbering, quota and prerequisite facts. Dense but every sentence carries operational information; the quota sentence is slightly tangential but still decision-relevant.

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 16-parameter mutation tool with no output schema, the description covers prerequisites, side effects and limits well, but never says what the call returns (e.g. the new document's id) or whether the draft can be edited/deleted afterwards. An agent needs that to chain into update_invoice or send_invoice.

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 75%, so most parameters are already documented in the schema (currency defaults, discount units, line fields). The description adds meaning only for the aggregate behaviors (lines accepted, billing details and client copied), not for individual optional parameters such as boardId, terms or taxLabel.

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 ('Creates a draft invoice or estimate') plus the scope of what gets copied onto it. It is clearly distinguishable from siblings like send_invoice, update_invoice, convert_estimate_to_invoice and create_invoice_from_work because it emphasizes that the result is a private draft with no number.

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

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

Gives a real prerequisite ('Needs the billing details to be set up') and makes clear this is the draft-creation step, with sending deferred elsewhere ('sending takes the next one from the profile's counter'). It does not explicitly name sibling alternatives such as preview_invoice_from_work or create_invoice_from_work, so it falls 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?

Goes well beyond the annotations: it discloses the downstream consequence that lines become tied to the invoice and 'cannot be invoiced twice or edited until it is voided', that the draft is private with 'nothing is sent', that it consumes a free-plan quota ('2 documents per month'), and the owner-only auth requirement. These are exactly the side-effect, auth, and rate-limit facts an agent needs before a destructive write.

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 distinct information, with the core action front-loaded and the gating requirements placed where an agent will see them. Slightly dense, but nothing is padding or restated from the schema.

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

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

For a 25-parameter destructive write with no output schema, the description covers the operation, its irreversibility window, the preview fallback, quota impact, and auth scope. The remaining parameter detail is legitimately delegated to the schema and the referenced preview 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 coverage is 64% across 25 parameters, so the schema already documents most of the surface. The description adds real meaning for confirm and amount (gating semantics, 'Must equal the total or nothing is done') and gestures at includeTime/includeExpenses via 'finished billable hours and billable expenses become lines', but leaves many parameters (timeEntryIds, expenseIds, from/to, groupBy) to the schema and the 'same options as the preview' hand-wave.

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 plus the source material ('Creates a draft invoice from a project's unbilled work'), which cleanly separates it from create_invoice, convert_estimate_to_invoice, and preview_invoice_from_work. The parenthetical 'same options as the preview' explicitly anchors it to its sibling.

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 hard prerequisite ('Needs confirm: true and amount equal to the total of the preview') and states the fallback behavior when they are absent ('the result is that preview'), plus an ownership constraint ('Only the project owner'). It never names preview_invoice_from_work as the tool to call instead, so the alternative is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds no behavioral context beyond them. It does not disclose permissions required, whether labels are board-scoped, or what happens on duplicate names, so the burden carried by the description is minimal.

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

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

Two short, front-loaded sentences with the core action first. The color list duplicates the schema enum, which is mild waste, but the overall structure is tight.

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

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

For a mutation tool with no output schema, 0% schema coverage, and a board-scoped side effect, the description is too thin. It omits permission requirements, label scope, and error behavior.

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

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

Schema description coverage is 0% for three required parameters. The description only restates the color enum values already present in the schema, and says nothing about boardId or name semantics, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (create/adds a label) scoped to a board, which distinguishes it from update_label, delete_label, and set_task_labels. It is clear but does not explicitly differentiate itself from the sibling create_* tools.

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

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

There is no statement of when to use this versus update_label or set_task_labels, and no prerequisites such as the board needing to exist or whether the label becomes board-wide. Usage must be inferred entirely from the name.

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 disclose write/destructive/openWorld status, yet the description adds two genuinely useful facts beyond them: the return value ('Returns the new list with its id') and the authorization requirement ('Needs edit access to the board'). It does not discuss the destructiveHint implication, but the added auth and return context is real value.

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 sentences, front-loaded with the action, each carrying distinct information (what it does, the first-flag behavior, the return value, the permission requirement). No filler.

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

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

For a mutation tool with no output schema, the description covers the return value, the positioning option, and the required access level, and annotations cover the safety profile. Minor gap: no mention of where in a board workflow this fits or error conditions, but an agent has enough to call 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 coverage is 33%, so description must compensate, and it partially does by explaining the 'first: true' placement behavior and referring to the board. However 'title' and 'boardId' carry no added meaning beyond the schema, leaving one required parameter effectively undocumented.

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 (Adds) and resource (a list/column to a board), and even disambiguates the domain term 'list' as 'column'. An agent can distinguish this from create_board, create_task, update_list, and duplicate_list purely from the text.

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 explains the positional behavior of the new list ('at the end or, with first: true, before the other lists'), which is a usage hint, but it does not name sibling alternatives or state when-not to use it. Usage is implied rather than explicit.

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

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

Adds substantial context beyond the annotations: the Markdown body, the allowed link schemes, the 'refused, not cut' validation behavior on oversized text, and the required editor role on the project. This is strong disclosure for a write tool, though it doesn't touch the destructiveHint=true annotation (e.g., no explanation of side effects or lifecycle).

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 action and then the two kind definitions before constraints. Every sentence carries distinct, necessary information with no filler.

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

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

For a no-output-schema create tool, the definition covers permissions, content format, validation failure mode, and the kind choice, which is nearly everything an agent needs. The main remaining gap is any indication of side effects tied to the destructiveHint annotation.

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 75% schema coverage, the schema documents boardId and title, while the description contributes real meaning for kind (note vs discussion semantics) and content (Markdown, link scheme constraints, size limit). It goes beyond restating the schema, though it doesn't mention the title's 200-character bound.

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 (starts a note or discussion in a project) and defines the two kinds, which is the main ambiguity an agent faces. It never uses the word 'page' itself, so the resource name must be inferred from the tool name rather than the description, and no sibling (create_task, create_board) is explicitly contrasted.

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?

Offers clear in-tool routing by explaining what a note is versus a discussion and how their editing/commenting models differ, which directly guides the kind choice. It stops short of explicit when/when-not guidance against sibling tools such as update_page or add_page_comment.

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, destructiveHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: the created board consumes a slot against the free plan's board limit, and the project is created in 'active' state. It stops short of stating permission/auth requirements, so it is not a 5.

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

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

Three short sentences with the core action front-loaded, followed by quota impact and the alternative path. No filler; every sentence carries a distinct fact 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?

For a two-parameter create tool with annotations covering the safety profile and full schema coverage, the description is nearly complete: it explains what is built, the quota consequence, and the alternative for existing boards. It does not describe what is returned or how to reference the new project afterward, a minor gap given there is no output 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% and both parameters (title, clientId) are documented there, so the schema does the heavy lifting. The description only echoes the clientId semantics ('optionally for one of the user's clients') without adding format or constraint detail beyond the schema. 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 and resource ('Creates a new project') and pins down exactly what is produced: a board with the plain three-list layout plus project settings (active). It also differentiates from the update path by noting that converting an existing board is done via project settings, so an agent can separate this from create_board/update_project_settings.

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 (creating from scratch, optional client association) and one explicit redirect: 'To turn an existing board into a project, change its project settings.' It does not, however, distinguish this from close siblings like create_project_from_template or create_sample_project, which an agent would also consider for project creation.

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

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

The annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=true, but the description adds genuine context the agent would otherwise lack: the template is untouched, due dates are shifted onto the start date, and the new board counts against the free plan's board limit. That quota-consumption detail in particular explains the destructive hint and is real added value.

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 sentences with no filler; the core action is front-loaded and each remaining sentence carries distinct content (copy scope, source immutability, quota). Slightly dense but well ordered and appropriately sized for a five-parameter mutation.

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

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

With no output schema, the description should say something about the result (e.g. that it returns the new project or its id), but it does not. It adequately covers the required inputs and the mutation's side effects, leaving the return contract as the notable gap.

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

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

Schema coverage is 80%, so the baseline is 3, and the description earns a bump by disambiguating the templateKind enum ('starter or saved'), restating the startDate default semantics ('due dates shifted onto the start date, default today'), and clarifying that clientId is optional and constrained to the user's own clients.

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 ('Creates a new project from a starter or saved template') and enumerates exactly what gets copied (lists, labels, tasks with estimates and checklists, settings). It is clear what the tool does, but it never names the adjacent siblings (create_project, create_sample_project, create_task_from_template) to help an agent distinguish this from them without opening schemas.

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

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

There is no explicit when-to-use guidance, no when-not-to-use condition, and no alternative sibling named, despite the crowded create_* family. The 'Optionally for one of the user's clients' clause describes a parameter rather than usage context, so the agent must infer selection criteria from context alone.

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 well beyond the annotations: discloses that line items are snapshotted at creation time, that each generated invoice is left as draft/published-link/emailed per action, and that omitting confirm yields a read-only preview rather than a mutation. These are exactly the side-effect details an agent needs given 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?

Front-loaded with the core action, and every sentence carries information with no filler. It is a dense paragraph rather than structured bullets, which slightly hurts scannability for eight parameters, but nothing is wasted.

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 mutation tool with no output schema, the description covers side effects, the confirm gate, and copying semantics thoroughly. It doesn't say what the preview result contains or what errors look like (e.g., voided/estimate invoice ids), leaving a small gap.

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

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

Schema coverage is already 88%, so the baseline is 3; the description adds real value by tying interval/every/nextDate together ('every N weeks, months or years from nextDate') and clarifying endAfter as a cap. It doesn't further explain paymentTermsDays or invoiceId eligibility beyond the schema text.

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

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

Specific verb+resource ('Makes an invoice repeat') plus the exact mechanics: same client, lines, tax, notes and terms recurring every N weeks/months/years. It clearly distinguishes this from create_invoice (one-off) and update_recurring_invoice (modify an existing schedule) by describing creation of the recurring arrangement.

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

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

Gives clear operating context: 'Pro' plan gating, the confirm:true requirement with a preview fallback, and the action choice (draft/send/email) with the email precondition. It does not explicitly route the agent away from create_invoice or update_recurring_invoice, so it lacks named alternatives, but the when-and-how context is strong.

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 write, non-open-world, and destructive behavior, but the description adds rich operational detail about exactly what gets created, how much (six tasks, two weeks of hours), the 'one at a time' constraint, and free-plan/client-limit fallbacks. It does not explain the destructive aspect hinted by annotations (e.g., whether existing sample data is replaced), leaving a small gap.

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

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

The description is front-loaded and concise overall, but the first sentence is a long, multi-clause run-on that could be split for easier parsing. The second and third sentences are short. Overall efficient with no fluff.

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

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

Given no input schema, no output schema, and annotations that carry the safety profile, the description supplies the necessary operational context: what the sample project comprises, its labelling, concurrency limit, and quota interactions. It is nearly complete; only the destructive annotation's implication is left unexplained.

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?

Zero parameters, so the schema imposes no semantic burden; baseline for no-param tools is 4. The description correctly focuses on side effects rather than field-level semantics.

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

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

States the verb 'Creates' and precisely enumerates the resources (sample client, sample project with budget, six tasks, two weeks of hours) while marking the output as sample-labelled, which clearly separates it from create_project/create_client siblings that produce real data. An agent can identify the tool's unique role without opening the schema.

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

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

Provides clear context for use – populating reports, budget bar and timesheet with demo data – and a usage constraint ('One at a time'), plus limitation about free-plan board and client limit. It does not name when to avoid it or point to alternatives, so it stops short of the top score.

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, openWorldHint=false and destructiveHint=true, lowering the bar. The description adds real context beyond that: privacy scope ("Only the user sees it") and a quota (free plan allows 3 per board). However, it never explains the destructiveHint at all -- no mention of what happens when the 3-view limit is hit, whether an existing view is replaced, or what permissions are needed. Given the annotation explicitly flags destruction, that omission is a meaningful gap.

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 with the core action front-loaded and zero filler. Each sentence adds something (what is saved, who sees it, plan limit). Slightly fragmentary parenthetical style keeps it from being a model of structure.

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

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

With no output schema, the description need not explain return values, and annotations cover the safety profile. Yet for a 6-parameter creation tool at 0% schema coverage it leaves the required parameters unexplained and says nothing about failure modes (limit exceeded) or whether the created view is returned/addressable. Adequate conceptual framing, incomplete operational detail.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the load. It partially does: it names the four view enum values and maps the three filter categories (due date, labels, assignees) to the due/labelIds/assigneeIds properties. But neither required parameter (boardId, name) is explained, the due enum values are not enumerated, and the ID-array format for labelIds/assigneeIds is left implicit.

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

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

Specific verb + resource: "Saves a personal view of a board," and it goes further by enumerating what the view contains (board/table/calendar/timeline plus due date, labels, assignees filters). An agent immediately knows this writes a per-user view configuration. It stops short of naming the obvious counterpart (delete_saved_view) or otherwise differentiating itself from the many other create_* siblings, so a 5 is not warranted.

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 when this is relevant (you want a personal board view) but never states when to use it versus alternatives or any exclusions. The two facts it does give -- "Only the user sees it" and the 3-per-board free-plan cap -- are constraints rather than selection guidance. Minimum-viable context, no routing help.

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, destructiveHint=true and openWorldHint=false. The description adds real behavioral context beyond that: 'The board's rules for new cards run, as in the app,' which explains why a create call can have side effects, plus the Pro constraint that recurrence requires a due date. It does not explain return values, but for a create tool with annotation coverage this is solid.

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 the core action and resource before feature details. The parenthetical Markdown enumeration is the longest stretch and borders on padding, but it is informative enough to earn 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 an 8-param tool with nested objects and no output schema, the description covers creation semantics, target resolution, content format, side effects, and Pro constraints. The main omission is what the call returns (e.g., the created task identifier), which an agent may need for follow-up calls.

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

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

Schema coverage is only 63%, and the description compensates meaningfully: it documents that the `description` field becomes the card page and accepts Markdown (a detail absent from the schema), that recurrence is Pro-gated and needs a due date, and enumerates the optional features (due date, reminders, checklist). It adds utility beyond the structured fields, though not every undocumented param is covered.

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 ('Adds a task (card) to a list') and further specifies the fallback ('or to a board's first list when only boardId is given'). It also implicitly distinguishes itself from siblings like create_task_from_template and bulk_tasks by describing scratch creation. An agent can identify exactly what this does without opening the schema.

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

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

It gives conditional usage for two parameters (use listId, or boardId alone to target the first list), which is genuinely helpful routing guidance. However, it never says when to prefer this over create_task_from_template, bulk_tasks, or add_checklist/add_reminder — usage relative to alternatives is left to inference.

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 readOnlyHint=false and destructiveHint=true, yet the description says only that a task is 'added' — it never addresses why the operation is flagged destructive (does it consume or alter the template? is it reversible?) or what permissions are needed. With annotations doing the safety signaling, the description should have explained this tension, and instead adds nothing.

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 well-formed sentence with no filler; the action and source are front-loaded. It is appropriately sized, though the brevity is partly under-specification rather than disciplined concision.

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 write tool with no output schema, no annotation commentary, and 0% parameter documentation, the description leaves key gaps: required permissions, destructive behavior rationale, and parameter formats. An agent could invoke it, but without real confidence about side effects.

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

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

Schema description coverage is 0%, so the description must carry the burden, but it only loosely maps the two parameters to concepts ('a list', 'one of the board's card templates'). It gives no format guidance (ID vs name, where to obtain listId/templateId), leaving the agent to guess at values.

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 (adds) and resource (a task to a list), and names the source (card template), which implicitly separates it from the plain create_task sibling. It never names an alternative explicitly, so differentiation is inferable rather than stated.

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?

No when-to-use, when-not-to-use, or alternative is given, despite several closely related siblings (create_task, save_task_as_template, duplicate_task). The only guidance is the implied precondition that a card template on the board exists.

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 destructive/not-read-only; the description adds the real operational consequences: persistent external delivery of events, request signing via X-Decknote-Signature with a secret returned once in the response, free=1 / Pro=25 quota, and the confirm:true gate that otherwise yields only a preview. This is exactly the behavior an agent needs before invoking a write 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?

Dense but earned: purpose first, then kind, scope, events, quotas, and the confirm gate. It reads as a long run-on paragraph with several implicit abbreviations ('…', 'here'), which costs a little clarity but no sentence is filler.

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

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

For a 5-parameter write tool with no output schema, the description covers effect, scoping, payload format, security (signing secret returned once), quotas, and the preview/confirm contract. Nothing material is missing 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 only 40%, but the description compensates by explaining every parameter: kind semantics and the URL format each expects, boardId's ownership restriction and fallback scope (all boards plus invoices/estimates), events defaulting to all, and confirm's preview behavior. This adds substantial meaning beyond the bare 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 ('Adds a webhook') and immediately explains the effect: chosen board events get sent outside Decknote. It is clearly a creation tool distinct from update_webhook/delete_webhook/list_webhooks, though it never names those siblings explicitly.

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

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

Explains when each kind applies ('slack' for an incoming-webhook channel URL, 'json' for Zapier/Make/n8n/own server), how boardId scopes delivery versus omitting it, the event default, and the plan quotas. It lacks an explicit pointer to update_webhook/test_webhook for related follow-up actions.

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 destructiveHint=true; the description adds genuinely non-obvious behavior: the aggressive side effect on the task cover image and the fact that omitting confirm yields a non-mutating preview. That is exactly the extra context annotations cannot carry.

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, with the core destructive action front-loaded and the confirm requirement trailing. The parenthetical about the cover image earns its place as it prevents surprise data loss.

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

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

For a two-parameter destructive tool with no output schema and annotations covering the safety profile, the description supplies the essential missing pieces (preview gate, side effect). Minor gaps remain around permissions and reversibility, but nothing blocks 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 description coverage is 50%: 'confirm' is already fully documented in the schema, so the description's restatement adds little, while 'attachmentId' has no schema description and gets no format/ID guidance here either. Partial compensation only.

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 (deletes) and resource (an attachment from a task), and goes further by disclosing a secondary effect: removal of the task cover if the attachment was the cover image. This is unmistakably distinct from the nearby rename_attachment and add_attachment 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 implies a two-step preview-then-confirm workflow via 'Needs confirm: true', which is usable guidance, but it never states when to choose this tool over alternatives or what preconditions exist (e.g., permissions). Usage is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety baseline is covered. The description adds genuinely useful non-obvious behavior: the operation is a no-op preview unless confirm is exactly true, and any non-true value degrades to preview. It omits whether the preview reports affected items or what permissions are needed.

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

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

Two short sentences with the destructive/preview caveat front-loaded right after the purpose; no filler. Slightly telegraphic, but every clause carries weight.

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

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

For a two-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies the critical behavioral fact (preview-by-default). The main remaining gap is that the preview result format is unstated, though the absence of an output schema makes that a moderate shortfall rather than a critical one.

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 50%: confirm is already fully documented in the schema, and the description essentially restates that same contract, while automationId remains unexplained in both places (no format, no hint on where to obtain it). With half the schema undocumented, the description does not compensate enough to exceed 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?

The description gives a specific verb+resource: 'Deletes a board rule,' which maps cleanly to delete_automation and distinguishes it from sibling deletions like delete_board, delete_task, or delete_list. It doesn't explicitly name or contrast with siblings such as set_automation_enabled (disable vs. delete), so it falls just short of a 5.

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

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

The confirm/preview note implies a two-step usage pattern (preview first, then commit), which is real usage guidance. However, it never states when to delete an automation versus disabling it via set_automation_enabled, nor any prerequisites such as permission requirements. Usage is implied rather than stated.

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

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

Adds substantial detail beyond the destructiveHint annotation: it discloses that all nested content (lists, cards, comments, attachments) is destroyed, that shared users are affected, and that the operation is irreversible. It also describes the confirm-based preview behavior, which is critical for a destructive 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?

Three compact sentences, front-loaded with the primary action and scope, followed by the irreversibility warning and the confirm preview behavior. Every sentence earns its place with no filler.

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

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

For a destructive delete tool with no output schema, the description covers the critical agent needs: what will be deleted, the irreversibility, the sharing impact, and how to preview safely. 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?

The schema already documents the confirm parameter in detail, and the description repeats that preview behavior. For boardId, the description adds only the ownership constraint ('a board the user owns'), which is helpful but not a full semantic treatment. With 50% schema coverage, this is adequate but not rich.

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 the exact verb and resource ('Permanently deletes a board') and specifies the cascade scope: lists, cards, comments, attachments, and shared users. The use of 'permanently' and 'Irreversible' distinguishes it from reversible board operations such as archive_board or restore_board, even though no sibling is named explicitly.

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

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

The description explains the confirm preview mechanism, which is useful usage context, but it does not state when to choose this tool over alternatives like archive_board or delete_list. The implied usage is clear from the verb, yet no explicit guidance or exclusions are 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 destructive and non-read-only. The description adds real behavioral context beyond annotations: the two-phase preview/confirm model and that dependent tasks survive the deletion. It stops short of describing reversibility or permission requirements.

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 its side effect, then the confirmation requirement. Every clause earns its place.

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

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

No output schema, so the description should carry return behavior — it does explain the preview vs. execution outcome. Given annotations covering destructiveness and a small 2-param schema, this is nearly complete; only auth/reversibility detail 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 50%; the description compensates for the undocumented templateId (implied target) and reinforces confirm's exact semantics. The schema already spells out confirm's behavior, so the description largely echoes it, but it adds the preview-framing which is genuinely useful.

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 ('Deletes a card template') and immediately disambiguates from other delete tools by clarifying the effect on derived tasks ('tasks made from it stay'), which is the key distinguishing behavior versus delete_task or delete_board.

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?

Clearly explains the confirm semantics — without confirm:true you get a preview rather than the deletion. It does not, however, explicitly route to siblings (e.g., archive vs delete) or state when deletion is preferred over archiving.

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 safety is partly covered, but the description adds real value by disclosing the two-phase confirm/preview mechanism and that all items are removed. It stops short of stating irreversibility or permission requirements, but the preview semantics are a meaningful addition beyond 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?

Two tight sentences with no waste; the destructive scope is front-loaded and the confirm requirement follows immediately. Every clause earns its place.

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

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

For a destructive delete tool whose annotations carry the safety profile and with no output schema to explain, the description covers the key behaviors an agent needs: what is deleted, and that confirmation is required. The undocumented checklistId leaves a minor gap.

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

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

Schema coverage is 50%: the confirm parameter is fully documented in the schema, and the description largely restates it, while checklistId has no description anywhere. The description does not compensate for the undocumented checklistId, so it adds little beyond structured data.

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 ('Deletes') and resource ('a checklist') and adds scope ('with all its items'), which cleanly distinguishes it from the sibling delete_checklist_item. An agent can tell what gets removed without opening the schema.

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

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

The description explains the confirm: true requirement and the preview fallback, which is useful operating guidance, but it never states when to choose this over alternatives like delete_checklist_item or archive/update paths. Usage is implied rather than explicitly routed.

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 safety profile is known. The description adds real behavioral context beyond that: the dry-run/preview mode when confirm is absent or not boolean true, and the invariant that the final checklist item cannot be removed here. It does not describe the preview payload's contents, but for a destructive tool this is solid added value.

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

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

Three short sentences, zero filler, and the ordering is effective: core action first, then the constraint caveat, then the confirm-gating requirement that an agent must act on.

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 two-parameter tool with no output schema, the description covers the essentials: what is destroyed, the last-item guard, and the confirm gate including preview behavior. The only real omission is any sense of what the preview returns or how errors surface when the last item is targeted.

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

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

Schema coverage is 50%: confirm is fully documented in the schema and restated in the description with the same semantics, but itemId has no description in either place. The description implies itemId is the item being deleted but adds no format or sourcing guidance, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource (delete one checklist item) and immediately bounds the scope against the sibling delete_checklist by explaining that a checklist always keeps at least one item, so the last item requires deleting the whole checklist. An agent can distinguish it from delete_checklist, update_checklist_item, and delete_task 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 concrete conditions for correct invocation: confirm: true is required for the action, and omitting it yields a preview rather than a change. It also warns about the last-item case. It does not explicitly name the alternative (delete_checklist) as the route for full removal, so the routing guidance is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, so the bar is lower, yet the description adds substantial context beyond them: owner-only authorization, immediate effect on the client page, the confirm=true preview mechanic, and the scope covering both client comments and team answers. Nothing about consequences is left implicit.

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 tightly packed sentences with no waste, front-loading the action and permanence, then scope, then authorization and the confirm gate. The parenthetical examples earn their space by clarifying intent.

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

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

For a two-parameter destructive tool with no output schema, the description supplies everything an agent needs: authorization requirement, confirmation semantics, side effects, and scope. No meaningful gap remains given that annotations cover the safety profile and the schema covers the parameters.

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 itself documents confirm's preview behavior and commentId. The description restates the confirm requirement but adds no syntax, format, or lookup guidance beyond what the schema already provides, 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 (permanently removes), resource (one comment), and scope (task conversation on the client portal), which distinguishes it from sibling delete_comment and delete_page_comment. An agent can tell which comment surface this targets without opening the schema.

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

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

Gives clear usage context (spam, a mistake), a prerequisite (only the project owner), and the confirm/preview flow. It does not explicitly name the alternative tools (e.g., delete_comment for internal comments), so it stops short of full when-vs-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 declare destructiveHint=true and readOnlyHint=false, so the write/destructive nature is covered structurally. The description adds two things the annotations cannot: the ownership-based authorization rule and the confirm gate that makes the call a preview by default — a genuinely non-obvious safety behavior for a destructive 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?

Two sentences, no filler, with the destructive action and the confirm requirement both front-loaded. 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?

For a two-parameter destructive tool with annotations covering the safety profile and no output schema, this is nearly sufficient: action, permission scope, and the preview default are all stated. It stops short of covering failure modes (nonexistent/already-deleted comment) or whether replies to the comment are affected.

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 50%: 'confirm' is fully documented in the schema, while 'commentId' carries no description. The description restates the confirm semantics (already in the schema) and adds nothing about what a comment ID is or where to obtain it, so it neither compensates for the gap nor falls below the baseline for this coverage level.

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

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

Specific verb ('Deletes') plus resource ('a comment'), and it goes further by stating the authorization scope in parentheses: the user's own comments or any on a board the user owns. This distinguishes it from edit_comment and delete_task-style siblings 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?

The description clarifies who may delete what, which is a real usage constraint, but it never names an alternative (edit_comment, react_to_comment, delete_task) or states when deletion is preferable to editing. Usage is implied by the permission scope rather than explicitly guided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuine behavioral context beyond that: the two-phase confirm/preview mode and the fact that the deletion cascades to the field's value on every card — neither is derivable from the annotations.

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

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

Two tight sentences, with the destructive effect front-loaded and the confirm requirement immediately after. 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?

No output schema exists, and the description covers the critical call semantics (preview vs commit, cascade). It could still say whether the deletion is reversible or what permissions are required, but for a 2-parameter tool it is close to complete.

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

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

Schema coverage is 50%: confirm already has a thorough schema description that the prose largely restates, while fieldId is undocumented in both schema and description. With 2 parameters and one half-documented, 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?

States a specific verb (deletes), the exact resource (a custom field), and the blast radius (its value on every card), which an agent cannot infer from the name alone. It is clearly distinguishable from sibling delete_* tools that target different resources like delete_label or delete_list.

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 supplies the confirm:true precondition, which is a real usage instruction, but gives no guidance on when deletion is preferable to keeping the field or using update_custom_field instead, and no warning about irreversibility or when-not-to-use.

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 destructiveHint=true/readOnlyHint=false; the description goes well beyond by disclosing that deletion is permanent, the permission model (logger or project owner), and the confirm-gated preview behavior. These are exactly the behavioral traits an agent needs before invoking a destructive 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?

Three tight sentences with no filler; the destructive scope is front-loaded, followed by permissions and then the confirm gate. Every sentence carries distinct, actionable information.

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

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

With no output schema, the description adequately covers destructiveness, permissions, and the confirm/preview flow. It leaves minor gaps such as error behavior when the expense is already on an invoice or whether related data is affected.

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 both parameters are documented there, so the baseline is 3. The description restates the confirm:true requirement and the preview semantics, which mirrors rather than extends the schema's own wording.

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 (permanently deletes) and resource (an expense), plus a scoping precondition (not yet on an invoice) that separates it from update_expense and list_expenses. An agent can identify the operation and its domain constraint without opening the schema.

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

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

Gives clear when-to-use conditions: only for expenses not yet on an invoice, and only by the person who logged it or the project owner. It stops short of naming an explicit alternative (e.g., remove from invoice first, or update_expense), so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true, so "for good" adds little; the real value is the disclosed permission model and the dry-run preview behavior when confirm is absent. It doesn't cover error cases (e.g., missing receipt, insufficient rights), keeping it below 5.

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

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

Three short sentences, front-loaded with the action and permanence, then authorization, then the confirm mechanic. No filler.

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

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

For a destructive 2-parameter tool with no output schema, the description covers permanence, authorization, and the preview safety valve — the key facts an agent needs to call 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 coverage is 100%, so both parameters (receiptId, confirm) are already documented in detail. The description's remark about confirm:true largely restates the schema's own explanation, 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 and resource ("Deletes a receipt of an expense") and adds permanence ("for good"). This cleanly isolates it from the sibling delete_expense (deletes the expense) and add_expense_receipt without needing to name them.

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

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

Gives concrete invocation guidance — who is authorized (the logger and the project owner) and the confirm:true requirement with preview fallback. It doesn't explicitly exclude sibling tools or say when deleting a receipt is preferable to updating/removing the expense, so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond the destructiveHint annotation: deletion is permanent, hours and expenses return to unbilled work, a source estimate can become an invoice again, and the draft stops counting toward the free-plan allowance. It also explains that omitting confirm yields a preview rather than performing the deletion.

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

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

The description is front-loaded with the core action and then explains consequences and the confirm requirement. Every sentence contributes useful information for a destructive operation.

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

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

There is no output schema, and the description covers the key behavioral details: irreversibility, side effects on unbilled work and estimates, billing impact, and the confirm/preview distinction. An agent has enough context 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 schema already documents both invoiceId and confirm. The description reinforces the confirm preview behavior but does not add parameter meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: it deletes a draft invoice or estimate. It also scopes the operation to drafts only, which distinguishes it from actions on sent or numbered invoices.

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 clearly says the tool applies only to drafts that were not sent and have no number, and it explains that confirm: true is required. It does not explicitly name a sibling alternative such as void_invoice for non-draft invoices, so it falls short of full sibling routing guidance.

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

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

Annotations already flag destructiveHint=true, but the description adds the crucial detail annotations cannot express: exactly what is destroyed (the label and its application on every card). It also discloses the dry-run/preview safety behavior of the confirm gate, which is valuable behavioral context for a destructive operation.

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

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

Two tight sentences, front-loaded with the primary effect and immediately followed by the confirmation requirement. No filler or restatement 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?

For a simple two-parameter destructive tool with no output schema, the description covers the effect scope and the confirm/preview mechanic well. It omits permission or authorization requirements and whether the deletion is reversible, which would be useful for a destructive operation.

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

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

Schema description coverage is 50%: confirm is fully documented in both schema and description (redundant but consistent), while labelId has no description anywhere. The description does not compensate for that gap, though the parameter name is largely self-explanatory.

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 ('Deletes a label from a board') and goes further to define the scope of the deletion ('removes it from every card that has it'). This cascade detail cleanly separates it from siblings like update_label, create_label, and delete_list.

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

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

The description clearly states the invocation precondition ('Needs confirm: true; without it the result is a preview'), which tells the agent how to actually execute versus preview. It does not, however, mention any alternative tool or when-not-to-use case (e.g., renaming via update_label instead of deleting).

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: the deletion cascades to all cards including archived ones, it is irreversible, and omitting confirm produces a preview with the number of cards that would be lost. That is exactly the behavioral detail an agent needs before invoking a destructive 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?

Three short sentences are front-loaded with the core action, then irreversibility, then the confirmation requirement. Every sentence adds distinct information and none is padding.

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

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

For a destructive cascade tool with no output schema and full destructive annotations, the description covers consequences, irreversibility, and preview behavior well. Minor gaps remain: listId semantics are not documented, and no permissions or side effects beyond card deletion are mentioned.

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 moderate at 50%. The confirm parameter is already fully described in the schema, and the description mostly restates that behavior while adding the preview detail ('number of cards that would be lost'). The required listId parameter remains unexplained in both the schema and the description, though its meaning is largely evident from the name.

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 (permanently deletes a list) and clarifies the cascade scope (every card, archived included). The word 'permanently' distinguishes it from archive siblings such as archive_board and archive_task, so an agent can tell it apart without opening sibling 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?

It explains the confirmation precondition ('Needs confirm: true') and the preview fallback, which is useful invocation guidance. However, it does not say when to choose delete_list over alternatives such as archive_task, update_list, or restore_task, leaving routing to inference.

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, but the description adds the cascade ('with all its comments'), the authorization rule, and the dry-run preview semantics of omitting confirm. That is meaningful behavior beyond the structured hints.

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 sentences, destruction and authorization front-loaded, no filler. The fragment 'Its author and the project owner can.' is slightly clipped and would read better with an explicit verb.

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 two-parameter tool with no output schema, the definition covers scope of deletion, permissions, and preview mode. It could say whether the deletion is recoverable or what the preview returns, but 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 coverage is 100% and both parameters are fully documented in the schema, including the exact confirm/preview contract. The description restates confirm rather than adding syntax or constraints, 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 ('permanently deletes') and resource, and disambiguates 'page' as 'a note or a discussion'. The word 'permanently' also separates it from the sibling set_page_archived, so an agent can route correctly.

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 real preconditions: only the author and the project owner may call it, and confirm:true is required or the call degrades to a preview. It does not, however, point to an alternative such as archiving when a reversible action is wanted.

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, but the description adds genuinely new behavioral context: the deletion is permanent, is authorization-gated, and without confirm:true only a preview is returned. It omits whether cascading effects occur (e.g., replies) or whether the action is recoverable.

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

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

Three short sentences with the core action front-loaded and the confirm requirement last. 'Its author and the project owner can.' is telegraphically clipped but not wasteful; nothing extraneous is included.

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 two-parameter tool with no output schema, the description covers the essentials: permanence, permission scope, and the confirm-preview mechanism. Only edge cases such as recovery or side effects on dependent data are left unstated.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, and the description's confirm sentence largely restates the schema's own text. Baseline 3 is appropriate since the description adds no extra syntax or edge-case detail.

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

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

States a specific verb+resource ('Permanently deletes a page comment') that identifies the target object precisely. It implicitly separates itself from delete_comment/delete_client_comment by naming the resource, though it never explicitly contrasts with those 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 two concrete prerequisites: who is permitted ('Its author and the project owner can') and the required confirm:true flag with the preview fallback. It does not state when to prefer this over edit_page_comment or the other delete variants, so it stops short of full routing guidance.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond that by disclosing permanence, the non-cascading effect on already-created projects, the prohibition on deleting starter templates, and the confirm-gated dry-run behavior. These are exactly the behavioral traits an agent needs before invoking a destructive 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?

One compact sentence with the destructive action front-loaded, followed by the two side-effect caveats and the confirm requirement in parentheses. No filler and nothing repeated from the schema verbatim.

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

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

For a two-parameter destructive mutation with full schema coverage, destructive annotations, and no output schema, the description supplies everything missing: irreversibility, blast radius, restricted targets, and the confirm gate. Nothing an agent needs to call this correctly is absent.

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 confirm semantics are already documented in the schema; the description restates them but adds a constraint on templateId (starters cannot be deleted) that the schema's terse 'A saved template of the user' does not convey. Baseline would be 3, lifted slightly by that added eligibility constraint.

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

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

States a specific verb and resource (permanently deletes a saved template) and immediately scopes the effect: projects made from the template are untouched, and starter templates cannot be deleted. This distinguishes it from nearby siblings like delete_card_template, delete_sample_project, and archive_* operations 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?

Clearly conveys the calling context: this is the tool for removing a saved template, and it requires confirm: true or the call only produces a preview. It does not explicitly name alternatives (e.g., list_project_templates for discovery, or rename_project_template), but the confirm/preview gate gives concrete guidance on how to invoke it safely.

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