craaft

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The word 'Append' adds a small amount of behavioral context (items go to the end, and repeated calls can create duplicates, consistent with the non-idempotent hint), but the description does not state this explicitly or cover permissions or limits.

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 zero filler, and the action and target are front-loaded. For a two-parameter tool this is an appropriately sized description.

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 full schema coverage, a declared output schema, and annotations covering the safety profile, the description supplies enough for an agent to invoke the tool correctly. Only minor gaps remain, such as checklist-existence prerequisites and permissions.

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% (card_id as UUID, text with a 1000-character limit), so the schema carries all parameter meaning. The description adds nothing beyond what the schema already documents, making 3 the appropriate 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 states a specific verb ('Append') and resource ('an item to a card's checklist'), which clearly separates it from sibling tools like update_checklist_item, delete_checklist_item, and add_comment. It does not explicitly name a sibling or scope limitation, so it falls just short of 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?

There is no when-to-use guidance, no prerequisites (e.g. whether the checklist must already exist), and no mention of alternatives such as update_checklist_item. Usage is only implied by the verb.

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 the safety profile (not read-only, not destructive, not idempotent), and the description adds a genuinely non-obvious behavioral fact: the server assigns a stable key that card operations use as 'column'. It does not cover where the column lands in ordering 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 short sentences, front-loaded with the action and followed by the one piece of non-obvious context. Nothing is wasted or repeated 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?

An output schema exists, so return values need no explanation, and the annotations cover the mutation safety profile. The description is nearly sufficient for a two-parameter mutation, though ordering/permission context would round it out.

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% with only two well-documented parameters, so the schema already carries the semantics. The description adds no field-level detail (e.g. title length, UUID format) beyond what the schema states, making the baseline 3 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 ('Add a column to a board'), which cleanly separates it from update_column, archive_column, and delete_column. It does not explicitly name a sibling, but the create-verb makes the intent 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?

No guidance on when to add a column versus using update_column or archive_column, and no prerequisites (e.g. board permissions) are stated. Usage must be inferred entirely from the verb.

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

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

Annotations only declare the basic safety profile (not read-only, non-destructive, non-idempotent), so the description carries the interesting load and does so well: it names the exact endpoint, the markdown body and length limit, and the non-obvious notification rules (@username notifies viewers but never the author; no mentions notifies followers). It never states that repeated calls create duplicate comments, which is the one behavioral trait an agent would still want.

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 purpose is front-loaded and the notification rules earn their place by conveying non-obvious behavior. The middle sentence's endpoint path plus two documentation URLs is somewhat heavy for a two-parameter tool, but it is not 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?

With an output schema present, return values need not be described, and the description covers purpose, notification side effects, and body constraints. The only meaningful gap is the lack of duplicate-on-retry behavior, which is relevant given idempotentHint=false.

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 both parameters are already documented in the schema, and the description's markdown/5000-character detail simply restates the body parameter's schema text. Baseline 3 is appropriate since the description adds no new syntax, format, or constraint information for card_id or body.

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

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

The opening sentence gives a specific verb and resource ('Add a comment to a card'), and the verb inherently separates this tool from update_comment, delete_comment, and get_comments in the sibling list. An agent can identify the operation without consulting 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?

Usage is implied rather than stated: the notification semantics (mentions vs. no mentions) hint at when the tool matters, but there is no explicit 'use this when' guidance or comparison against update_comment/delete_comment for adjacent needs. An agent must infer the 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 declare this is a non-destructive, non-idempotent write, so the description is not obligated to restate that. It adds genuinely useful context the annotations lack: the authorization model (workspace owners/admins or explicit board admins). It stops short of saying what side effects occur (e.g. member notifications), so 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?

Two sentences, zero filler, with the action stated first and the permission constraint second. Nothing could be removed without losing 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 three-parameter create tool with a full schema, an output schema, and safety annotations, the description covers purpose and authorization adequately. The only minor gap is behavior on duplicate names or invalid due dates, which is not addressed anywhere.

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?

All three parameters are required and schema description coverage is 100%, so name length, date format, and UUID type are already documented in the schema. The description adds nothing parameter-specific, which is the expected baseline when the schema carries the load.

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 ('Add a milestone to a board'), which is unambiguous against siblings like update_milestone and delete_milestone. It does not explicitly name those siblings, but the action is clear enough that no differentiation is needed.

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 a real prerequisite — board admins only, with the owner/admin distinction spelled out — but gives no guidance on when to create a milestone versus updating or listing one, nor what happens with duplicates or invalid dates. Prerequisite coverage without selection guidance lands at 3.

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=false and idempotentHint=true, so the bar is lower, yet the description still adds real behavior: the card remains searchable and retrievable via list_archived_cards until restored, and invalid targets produce an error rather than silent success. One nuance is unaddressed: calling this on an already-archived card errors despite idempotentHint=true, which an agent could read as either a harmless no-op or a failure.

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, zero filler, and the core semantics are front-loaded before the lifecycle detail and the error condition. Each sentence contributes distinct 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 an output schema present, the description need not describe return values, and it still covers the reversible lifecycle, the observable effect, and failure conditions for a single-parameter mutation. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% for the single card_id parameter, so the schema already carries the load. The description adds nothing about the identifier's form or source, so the baseline of 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 and immediately defines the operation's semantics: 'take it off its board without deleting it,' which cleanly separates it from delete_card in the sibling list. A reader knows exactly what state change to expect 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?

Explains the condition under which this is the right tool (removing a card while preserving it) and names list_archived_cards as where the result surfaces, plus the error cases for already-archived or unreachable cards. It stops short of explicitly routing to delete_card or restore_card as alternatives, so it is clear context rather than 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?

Goes well beyond annotations by disclosing a silent-failure mode: non-done columns return 200 with a count of 0 rather than an error, and the caller must inspect the returned count instead of assuming success. It also confirms reversibility and points at restore_card for undo, which is exactly the behavioral context annotations (idempotentHint/destructiveHint) 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 sentences, each carrying distinct load: definition, reversibility, precondition/silent-no-op, and undo path. The critical warning is flagged and front-loaded within the paragraph; there is no restatement of the title or schema.

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

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

Covers the mutation's semantics, its hidden precondition, its failure signature, and its recovery path, and an output schema is present so return-value shape need not be re-explained. Nothing an agent needs before calling this 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?

Only one parameter and schema coverage is 100%, with the schema itself clarifying 'the id, not the key' on column_id. The description adds nothing further about the parameter, so this is the baseline case where the schema does all the work.

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 ('Archive every card currently in a column') and immediately scopes it against the obvious confusions: cards leave the board but 'are not deleted, and the column itself stays.' An agent can distinguish this from archive_card and delete_column without opening either schema.

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

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

Gives a hard precondition for use ('only archives cards in a column marked as a done column') and names the recovery path ('undo the sweep by calling restore_card on each one'). It does not explicitly name a sibling alternative for the non-done-column case, 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?

Goes well beyond the annotations: annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=false, but the description discloses atomic all-or-nothing semantics ('a failure leaves no half-imported board'), the diverging assignee default, and the suppressed notification emails. These are exactly the side-effect details an agent needs before a bulk 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?

Three sentences, each carrying distinct load: what it does, why to prefer it, how it differs from create_card. Front-loaded with the capability and the preference directive; 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?

An output schema exists so return values need not be described. The description covers capacity limit, transaction semantics, rate-limit cost, notification behavior, and default-value divergence — everything needed to invoke this safely in place of repeated create_card 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 100% and the schema already documents both parameters, including the per-card required fields and optional attributes. The description adds only the 'up to 100' limit, which the schema description also states, so it neither needs to nor does compensate further.

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 ... cards'), quantifies scope ('up to 100 cards on one board'), and names the batch boundary ('in a single transaction'). It also positively distinguishes itself from the sibling create_card, so an agent can route between them 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?

Explicitly directs the agent: 'Strongly prefer this over looping create_card,' giving both the alternative and the reason (one rate-limit token vs. one per card). No condition 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 already declare non-destructive, idempotent, non-open-world behavior. The description adds meaningful context beyond them: the operation is transactional, mixed-board ids without target_project_id return 400, and cards append to the end of the destination column.

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

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

Two sentences, front-loaded with the action and limit, then the two parameter-dependent cases. Every clause carries useful information and there is no filler.

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

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

Given an output schema exists and annotations cover safety traits, the description supplies the key remaining call-time context: bulk limit, atomicity, board constraints, and destination behavior. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantics for target_project_id beyond its schema text, specifically the same-board constraint when omitted and the mixed-board 400 error, plus append ordering when provided.

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 ('Sweep up to 100 cards into a column') and adds bulk scope ('one transaction'), clearly distinguishing it from the single-card sibling move_card without needing to name it.

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

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

Explicitly covers when to omit target_project_id (all ids must be on the same board) and when to provide it (move to that board and append to the target column). It does not name alternative tools or exclusions, but the conditions for the optional parameter are clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes well beyond that by disclosing transaction atomicity ('all-or-nothing: one bad item rolls the whole batch back'), error behavior ('the error names the offending index'), and the concurrency caveat ('never assume a failed batch partially applied') – exactly the operational traits an agent needs before invoking a bulk mutation.

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, each earning its place: capability, semantic equivalence to a sibling, and the atomicity/failure caveat. The critical constraint is front-loaded and there is no filler.

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

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

For a bulk mutation with annotations and an output schema present, the description covers the essentials the agent cannot infer: batch limit, transaction semantics, and failure/error behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the omit-to-leave / null-to-clear mechanics and the clearable field list are already documented in the schema. The description adds value by framing the parameter as partial updates and cross-referencing update_card for field semantics, though it doesn't restate the per-field rules 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 with scope: 'Apply up to 100 partial card updates in one transaction.' It also distinguishes itself from siblings by referencing update_card for field semantics, so an agent can tell it apart from update_card, bulk_create_cards, and bulk_move_cards 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?

It names the sibling whose semantics it mirrors ('Same field semantics as update_card') and gives a clear contextual constraint (batch of up to 100, single transaction). It stops short of an explicit when-to-use-this-vs-calling-update_card-repeatedly rule or 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 cover only the safety profile (readOnly=false, destructive=false, idempotent=false), so the description carries real behavioral weight: the card defaults to being assigned to and followed by the caller, due date/assignee/size/priority/tags are applied by a secondary update so a bad value yields an error naming an already-created card (non-atomic partial failure), and title/description mentions send notifications. These are side effects and failure semantics an agent cannot get 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?

Purpose is front-loaded in the first sentence and every clause carries information (defaults, failure mode, notifications, alternative tool). The middle sentence stacking the deferred-field list with an error path and a remedy is dense and dash-heavy, costing a point on readability rather than on length.

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

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

An output schema exists, so return values need no explanation. Given a 9-parameter create tool, the description covers defaults, deferred validation, recovery path, notification side effects, and the correct alternative tool — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter behavior the schema cannot express: that priority/due_date/assignee/size/tags are validated on a follow-up pass, and that assigned_user_id defaults to the caller plus follow-on. It doesn't restate per-field formats the schema already documents, which 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 ('Create a new card') plus a placement detail ('at the bottom of a column'), which is more than the title offers. It also names the sibling it is not for ('Use bulk_create_cards for more than one card'), so an agent can separate it from bulk_create_cards and add_checklist_item 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?

Explicitly routes the agent: use bulk_create_cards for more than one card, and if a follow-up field errors, use update_card rather than re-creating. Both the when-to-use and the when-not-to-recreate cases are stated outright, not inferred.

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, it discloses a non-obvious response limitation: create never includes columns, and get_project must be called on the new board id to read real column keys. It also states the Free workspace cap of 3 projects and the 402 error beyond that, which is valuable operational context.

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 main action and then adds important caveats. It is somewhat dense, especially the long IMPORTANT sentence, but every clause carries useful information for correct invocation.

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?

Despite having an output schema, the description correctly calls out that the creation response lacks columns and explains the follow-up needed to obtain them. It also covers template selection and quota behavior, making it 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 100%, so the schema already documents all three parameters. The description adds useful semantic context about template keys coming from list_board_templates and clarifies that only the default kanban template uses todo/doing/done keys, which is not fully captured by the schema alone.

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

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

The description gives a specific verb and resource ('Create a board') and immediately distinguishes the default-column behavior from the template-based behavior. An agent can identify this as the board-creation tool 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 clearly explains when to omit template versus when to pass one, names list_board_templates as the source, and instructs calling get_project after creation before creating cards. It does not explicitly compare with import_board or other creation alternatives, but the guidance for normal use is clear.

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

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

Adds substantial context beyond the annotations: admin/Pro-tier authorization with a 402 failure mode, the returned signing secret and X-Craaft-Signature header, the warning that the secret is never redacted on later reads, and the format-dependent signing behavior for slack/discord. This is exactly the kind of security- and auth-relevant disclosure 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?

Dense and front-loaded: the primary action, delivery behavior, and auth gating come first, with the secret/format caveats after. Every sentence carries information, though it is longer than strictly minimal.

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 webhook-creation tool with an output schema, the description covers everything an agent needs: prerequisites, side effects, the sensitive response artifact, and format-specific behavior. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the implications of the `format` parameter (signed JSON envelope vs. unsigned chat deliveries authenticated by secret URL) and tying the returned secret to the format. It clarifies semantics the terse schema descriptions leave 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?

States a specific verb+resource ('Register an outbound webhook on a board') and immediately distinguishes itself from siblings like list_webhooks, update_webhook, and delete_webhook by describing the create action and its delivery behavior. An agent can identify it without opening any schema.

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

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

Gives clear preconditions: board admin on a Pro board, with a Free workspace returning 402, and cross-references list_webhooks for the event catalogue. It does not explicitly state when to prefer this over update_webhook, but the create semantics and tier gating make usage clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered; the description still adds real value by disclosing exactly what is destroyed (metadata row plus stored bytes) and that the operation cannot be reversed. It does not mention side effects such as broken references on cards or required authorization, which keeps it out of the 5 band.

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 scope of deletion front-loaded ahead of the irreversibility warning. 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 one-parameter destructive tool with rich annotations and an output schema, the description covers purpose, effect, and irreversibility, which is nearly everything an agent needs. Minor gaps remain around error behavior (nonexistent ID) and permission requirements, but nothing critical is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents the attachment UUID fully. The description adds nothing about the parameter, which matches the baseline 3 when the schema does the heavy lifting.

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 precise verb and resource ('Delete an attachment') and sharpens the scope by clarifying that both the metadata row and the stored bytes are removed. It is unambiguous against siblings like delete_card or delete_comment, but it never names or contrasts any alternative tool, so it stops short of the top band.

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 'There is no undo' warning implies this is a last-resort, irreversible action, which is useful implied guidance. However, it gives no explicit when-to-use condition, no prerequisites (e.g., permissions or whether the attachment must be detached first), and names no alternative such as archiving or leaving the file in place.

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 idempotentHint=true, so the safety profile is covered structurally. The description reinforces this with 'This cannot be undone', which is useful but largely redundant, and it adds nothing about error behavior when the card is already gone (relevant given idempotentHint) or required permissions.

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, front-loaded with the action and immediately followed by the irreversibility warning. Nothing is padded or 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 one-parameter destructive tool with full schema coverage, complete annotations, and an output schema, the description covers what an agent needs. It could still mention the archive alternative, 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?

There is a single parameter with 100% schema description coverage ('card UUID to delete'), so the schema fully carries the semantics. The description adds no format or sourcing detail beyond it, making 3 the appropriate baseline.

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

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

States a specific verb and resource ('Permanently delete a card'), and the adverb 'permanently' implicitly distinguishes it from the archive_card/restore_card siblings. It does not name those siblings outright, so it falls short of the differentiation a 5 requires.

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 only implied: 'Permanently' signals the irreversible path versus archiving, but there is no explicit 'use archive_card if you want a recoverable removal'. An agent must infer the trade-off from the word 'Permanently'.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The word 'Permanently' adds a small amount of confirming context about irreversibility, but nothing about permissions, cascading effects, or side effects.

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

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

A single front-loaded sentence with zero filler; the verb-object structure is immediately readable. It is marginally under-specified rather than bloated, but nothing in it wastes space.

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 single-parameter destructive tool, an output schema already exists so return values need no explanation, and annotations carry the safety profile. The description is adequate, though it omits any mention of confirmation prompts or what happens to the parent checklist after removal.

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 clarifies 'checklist item UUID (not the card UUID)', which is the key disambiguation. The description adds no syntax, format, or parameter meaning beyond what the schema already provides, so the baseline of 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?

Clear specific verb (delete) plus resource (checklist item) with the 'Permanently' qualifier indicating irreversibility. It does not differentiate itself from the many other delete_* siblings (delete_card, delete_comment, delete_milestone), but the resource is unambiguous.

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

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

The description states only what the tool does, with no when-to-use guidance, no mention of the alternative update_checklist_item for modifying items, and no prerequisites or exclusions. An agent gets no routing help beyond 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 indicate destructiveHint=true and idempotentHint=true. The description adds significant behavioral detail beyond annotations: the 409 error on non-empty columns and the precondition preventing accidental data loss. This is exactly the kind of operational context that helps an agent avoid errors.

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 concise sentences that are front-loaded with the core action and immediately followed by the critical constraint. Every word 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 single-parameter tool with an output schema, the description covers the essential precondition, error behavior, and alternatives. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the single parameter column_id is fully documented in the schema. The description adds no syntactic or formatting details beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (column), and adds the crucial precondition that the column must be empty. It clearly distinguishes itself from siblings like delete_card or archive_column by naming the alternative (archive_column) and error condition.

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

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

Explicitly states when this tool applies (empty column) and what to do otherwise (move cards with bulk_move_cards or clear with archive_column). This is a textbook example of routing the agent to the correct alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds context the annotations cannot: the exact permission model (author or workspace owner/admin). It does not state whether deletion is permanent or recoverable, which keeps it below 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?

Two short sentences, zero filler, with the action stated first and the permission constraint second. 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 single-required-parameter destructive tool with an output schema available for return values, the description covers the action and the permission gate adequately. The one meaningful gap is failure behavior (what happens if the caller lacks permission, or if the comment is already gone).

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% for the single comment_id parameter (documented as a comment UUID), so the schema carries the parameter burden. The description adds no format or sourcing detail beyond what the schema already provides, matching the baseline 3 for high coverage.

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

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

States a specific verb and resource ('Delete a comment') that an agent can immediately match to the intent. It does not explicitly differentiate itself from siblings like update_comment, but the name plus verb phrase makes the target unambiguous.

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

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

The description supplies the authorization condition for use ('Allowed for its author, or a workspace owner/admin'), which is real usage guidance. It stops short of saying when to delete versus editing a comment or what to do when permission is missing, so usage is implied rather than fully framed.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a permanent, repeatable write. The description adds the auth requirement (board admins only), which the annotations do not cover. It does not disclose side effects, such as whether cards or other references tied to the milestone are affected.

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, action first, constraint second, with no filler. It is efficient, though extremely terse 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?

An output schema exists so return values need no explanation, and the annotations carry the safety profile. The description still omits relevant details for a destructive tool, such as whether deletion is reversible or what happens to dependent records, leaving a modest 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?

There is a single parameter (milestone_id) with 100% schema description coverage, so the schema already documents it as a UUID. The description adds nothing further, which matches the baseline for a fully-covered 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 names a specific verb and resource ('Delete a milestone'), which cleanly separates it from siblings like delete_card, delete_column, and delete_comment. It does not, however, explicitly contrast itself with update_milestone or any archive-style alternative.

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?

'Board admins only' establishes a precondition for use, which is genuinely useful routing information. Beyond that there is no guidance on when deletion is appropriate versus updating or otherwise modifying a milestone.

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 idempotentHint=true, and the description adds real substance on top: the exact cascading scope (columns, cards, comments, checklists, attachments) and the irreversibility of the action. It does not add authorization requirements or clarify the delete-vs-archive semantic, so it stops short of full disclosure.

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, zero filler, and the destructive scope and irreversibility are front-loaded where an agent will read them before acting.

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 single-parameter destructive tool with a full output schema, the description supplies everything an agent needs to decide safely: what is removed, that it cascades, and that it cannot be undone. No return-value explanation is required given the 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?

Only one parameter exists and the schema documents it fully at 100% coverage, so the baseline is 3. The description adds no extra meaning about project_id, such as which identifier form is expected or where to obtain it.

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

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

States a specific verb and resource ('Permanently delete a board') and immediately qualifies the scope with the cascade list, which is far more informative than the bare name. An agent can distinguish it from sibling deletes like delete_card or delete_column and from the non-destructive archive_card 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?

The 'There is no undo' warning implies this should be used cautiously for truly unwanted boards, which is genuine usage context. However, no alternative is named (e.g., archive instead of delete when recovery may be needed), so the when-to-use guidance is only 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 cover destructiveness and idempotency, so the bar is lower. The description adds genuinely non-structured context: the admin-only authorization requirement and the fact that the operation is not gated by plan tier, which matters for a downgraded workspace. It stops short of describing effects on existing deliveries or error 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?

Three short sentences with zero filler; the action is front-loaded and the permission caveat 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?

An output schema exists, so return values need no explanation, and the description covers authorization and plan-gating. Slightly incomplete on post-delete effects (e.g., whether queued deliveries are discarded), but adequate for a one-param delete.

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 disambiguates the id ('the id field, NOT endpointId'). The description adds no parameter-level detail beyond that, so baseline 3 is appropriate for a single fully-documented param.

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 a webhook subscription'), which cleanly distinguishes it from the create_webhook, update_webhook, and list_webhooks siblings. An agent can select it without ambiguity.

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

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

Gives a clear precondition ('Board admin only') and a useful when-can-use caveat ('Not plan-gated, so a downgraded workspace can still remove one'). It does not explicitly name alternatives, but the delete verb makes the boundary with create/update obvious.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context beyond that: an authorization requirement (board admins only) and the plan-gating exemption. It does not say what happens to existing inbound email config, which keeps it from 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, each earning its place: the action first, then the permission constraint, then the plan-independence caveat. Nothing redundant, and the most decision-relevant fact is front-loaded.

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

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

With an output schema present, return values need no explanation, and the description covers action, authorization, and the plan-gating edge case an agent might otherwise assume away. It stops short of stating reversibility (that enable_inbound_email restores it) or post-state effects, which is the remaining 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?

Only one parameter (project_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, format, or sourcing guidance for the UUID beyond what the schema already states, matching the baseline 3 for schema-covered params.

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: 'Turn off email-to-card for a board.' It clearly distinguishes this mutation from the sibling enable_inbound_email and from the read-only get_inbound_email, so an agent can select it 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 the operative condition and prerequisite explicitly ('Board admins only'), and adds the noteworthy case that 'a downgraded workspace can still disable it.' It does not name enable_inbound_email as the inverse operation, so routing back 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 already declare destructiveHint=true and idempotentHint=true, and the description adds information annotations cannot express: the immediate effect on existing links and the irreversible token behavior on re-enable. That token-non-restoration detail is precisely the kind of consequence an agent needs before invoking 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 sentences, zero filler, with the core action stated first and the consequence second. Every clause carries decision-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?

An output schema exists, so return values need no explanation, and the description covers the destructive semantics well. The only meaningful gap is who is authorized to revoke sharing, which is not addressed in the description or annotations.

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?

Only one parameter, and the schema documents it at 100% coverage as 'project UUID,' so the baseline is 3. The description says 'board' while the parameter is project_id, adding no clarifying semantics and introducing a minor terminology mismatch.

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 and resource: 'Revoke a board's public link,' which tells the agent exactly what state change occurs and distinguishes it from the sibling enable_sharing. An agent can identify the operation 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 clearly frames usage context by noting that links stop working immediately and that re-enabling mints a new token, which is the key decision factor for calling this. It doesn't explicitly name enable_sharing as the counterpart or state prerequisites (e.g., required permissions), so it falls short of a full when/when-not/alternatives statement.

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?

Despite annotations already declaring readOnlyHint, the description adds substantial behavioral context: text files return as readable text, binaries as base64, the 25 MiB size reality, and the deliberate refusal-over-max_bytes policy that reports real size instead. This is exactly the kind of disclosure 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?

Three sentences, front-loaded with purpose then behavior, all earning their place. Slightly dense but no wasted words and no redundancy with 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?

An output schema exists, so return-format detail is not required. For a read tool with annotations covering safety, the description supplies everything an agent needs: format branching, size limits, and the refusal semantics.

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 further by explaining what max_bytes actually does behaviorally (refuses and reports real size; raise deliberately), adding interpretation beyond the schema's terse 'refuse to inline anything larger than this' 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?

The description states a specific verb and resource: 'Fetch an attachment's bytes.' This clearly distinguishes it from siblings like list_attachments (metadata listing) and upload_attachment (the inverse operation) 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?

Usage is implied by the tool's nature (you call it when you need an attachment's content), but there is no explicit when-to-use-vs-alternatives guidance, no mention of where attachment_id comes from in the description (it lives only in the schema), and no prerequisites or error paths beyond the max_bytes behavior.

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 only the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds non-obvious context the annotations cannot carry: the admin/Pro-plan authorization requirement, the created intake address, and the specific 409 conflict response. This is consistent with idempotentHint=false.

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

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

Three sentences, each earning its place: capability first, then the access constraint, then the failure path with alternatives. Front-loaded and free of 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?

An output schema exists, so return values need not be explained. Combined with the schema's per-parameter notes, the description covers preconditions, side effects, and the conflict case, leaving nothing an agent needs in order 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 explains project_id, target_column, and the ai_enrich error behavior. The description adds no parameter-level detail beyond the mention of an intake address, 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 and resource (enable email-to-card for a board) plus the concrete side effect of minting an intake address. This clearly separates it from get_inbound_email, update_inbound_email, and disable_inbound_email without needing to open any schema.

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

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

Gives the precondition (board admins on Pro boards only) and explicitly routes the agent elsewhere when the board already has an address: 'use update_inbound_email or disable_inbound_email first.' The condition that selects the alternative is named, not inferred.

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 declare idempotentHint=true and destructiveHint=false, but the description goes further by explaining the actual exposure semantics: anyone with the link can view without signing in and cannot add, edit or move anything. It also spells out the consequence of idempotency (existing token returned, URL stays stable). What it does not cover is who is authorized to enable sharing or any audit/rate considerations.

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: action and return value first, then the security-relevant scope of exposure, then the idempotency guarantee. 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?

An output schema exists, so return-value documentation is not required, yet the description still names the token and URL. For a one-parameter mutation with full schema coverage and annotations, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% for the single project_id parameter, so the schema already carries the parameter meaning. The description refers to 'a board' but adds no syntax or format detail beyond that, 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 and resource ('Turn on read-only public sharing for a board') plus the result (share token and URL). An agent can immediately separate this from disable_sharing and from grant_board_access, which governs per-user access rather than a public link.

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 scope ('read-only public sharing') implies when this is the right tool, and the idempotency note tells the agent it is safe to call without pre-checking state. However, it never names an alternative such as disable_sharing or grant_board_access, nor states prerequisites like required role/permission, so routing 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 already declare readOnlyHint=true, openWorldHint=false and idempotentHint=false, so the safety profile is covered structurally. The description adds one meaningful behavioral fact — the result is 'Returned as text' (inline, not a file artifact or URL) — plus a content sketch of each format, but stops short of anything else notable.

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 verb and resource, then the format semantics. No filler, no restatement of the title, every clause carries 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 read-only tool with an output schema present, the description is nearly sufficient: format choice, content of each format, and text delivery are all covered, and safety is handled by annotations. Only the routing against sibling read tools is unaddressed.

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 carry their own descriptions, including the json default. The description restates the format trade-off without adding syntax, defaults, or edge-case behavior 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 and resource ('Export a board') and immediately clarifies what each output format contains, which is the main ambiguity for an export tool. It never names the obvious sibling (import_board / preview_import) to reinforce direction, but the verb makes the distinction self-evident.

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 format descriptions imply when to pick JSON versus CSV (full snapshot vs flat row-per-card), which is genuine selection guidance. However it never says when to use export_project instead of get_board, nor any prerequisites or limits, so usage context 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?

Goes well beyond the annotations (which only mark it read-only, closed-world, non-idempotent) by disclosing the return shape, the 5 MiB size cap, and the crucial edge case that hasAvatar=false is a normal result rather than a failure. This is exactly the behavioral context an agent needs.

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

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

Two tight sentences with no filler; the core action is front-loaded and the size cap and edge-case handling follow immediately. Every clause carries 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 single-parameter read with an output schema, the description covers what matters: payload contents, a hard size bound, and the no-avatar case. Return-value structure is legitimately left to the output schema, so nothing critical is missing.

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

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

Only one parameter (user_id) and the schema already documents it at 100% coverage. The description adds no syntax, format, or lookup detail beyond the schema, 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+resource (fetch a user's avatar) and even summarizes the payload (URL plus base64 bytes). It is unambiguous, though it does not explicitly contrast itself with adjacent read tools such as get_me or download_attachment.

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; there is no explicit 'call this when...' clause or named alternative. It does supply a valuable conditional: a missing avatar is not an error and should trigger the initial-and-colour fallback, which is real guidance but not a when-to-use-vs-alternative statement.

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 openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: the response is deliberately partial (card descriptions omitted) and the brief must be read before touching cards. It stops short of disclosing volume limits, pagination, or whether archived cards are included.

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, zero filler. The return contents are front-loaded and the omission/routing guidance is compressed into a parenthetical and a follow-on clause rather than sprawling.

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

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

An output schema exists, so return-value shape need not be explained, yet the description still summarizes scope precisely. For a single-parameter read tool with full annotation coverage, nothing needed to invoke it correctly is missing.

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

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

There is a single parameter with 100% schema coverage ("the project UUID to load"), so the schema already carries the semantics. The description adds no syntax, format or scoping detail about project_id, leaving the baseline 3.

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

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

States a specific verb and resource ("Get a Kanban board") and enumerates exactly what is returned: columns, brief, and every card with a defined metadata set. It distinguishes itself from get_card and get_card_detail by explicitly naming what it omits (card descriptions) and pointing to 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 an explicit precondition for the brief ("read it before working on the board's cards") and routes the agent to specific alternatives with the condition that selects them: get_card for the body, get_card_detail for body plus comments, events, checklist and attachments in one call. This is a clear when-to-use-which decision 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 only declare readOnlyHint/openWorldHint/idempotentHint. The description adds substantial context beyond that: 12-month retention, that cardId is only populated while the card remains on the board (deleted cards keep title), that it works regardless of the board's activity-button setting, and that nextBefore is empty at the end of the feed. This is exactly the behavioral detail 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?

Front-loaded with purpose, then usage, then entry shape, then edge cases and pagination. Despite being long, every sentence carries distinct information and there is no filler or repetition.

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

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

Despite having an output schema (so return values need not be explained), it still summarizes entry fields and edge-case semantics. Combined with the pagination contract and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, types, before, actor_id and project_id, making 3 the baseline. The description adds only a small increment beyond that — the terminal condition of the before cursor — and otherwise restates structure 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 gives a specific verb+resource ('Get a board's activity feed') and then enumerates exactly which events are covered (cards added, moved, archived, restored, deleted; priority/assignee changes; comments; columns). It explicitly distinguishes itself from the sibling get_card_activity, so an agent can select 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?

It states the triggering question ('what happened on a board this week or who changed something') and names the alternative for the card-scoped case ('For one card's history use get_card_activity'). When-to-use and when-to-use-the-other are both 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=true and openWorldHint=false, so the safety profile is covered without description text. The description adds that the response includes the description field (which get_board omits), a useful content-scope note, but says nothing about auth requirements, failure modes on unknown IDs, or latency. Adequate-but-thin against an already-declared read-only profile.

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 clauses: what it returns front-loaded, then the two sibling-routing rules. Every sentence earns its place and there is no filler or restatement of the title.

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

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

With one required parameter, full schema coverage, an output schema that documents the return shape, and annotations carrying the read-only safety profile, the description supplies everything else an agent needs: scope of returned data and routing versus alternatives.

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 the single card_id parameter is documented as a card UUID in the schema, so the schema does the heavy lifting. The description only restates 'by its ID' without adding format or lookup semantics beyond the schema, which is the baseline 3.

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

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

States a specific verb and resource (get a single card by ID) and immediately scopes the return payload ('full metadata including description'). It explicitly distinguishes itself from get_board and get_card_detail by what each returns, so an agent can pick 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?

Gives explicit selection conditions both ways: prefer this over get_board when the card ID is known, and use get_card_detail instead when comments, events, checklist or attachments are needed. Exclusions and alternatives are spelled out, not inferred.

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 openWorldHint=false, so safety is covered; the description then adds ordering ('oldest first') and, importantly, the permission-dependent behavior that fromDetail/toDetail are omitted for boards you can't see. It does not mention pagination or result limits, keeping it short of full disclosure.

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, zero filler: purpose and scope first, usage motivation second, non-obvious field encoding third. Everything is front-loaded and each sentence carries information an agent would otherwise have to guess.

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 read tool with annotations covering the safety profile and an output schema covering the return shape, the description supplies the remaining unknowns — ordering and the <projectId>:<columnKey> encoding of moved_board fields. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single card_id is already documented as a card UUID. The description adds no syntax or format guidance for the parameter, so the baseline 3 applies; the rich field detail it does provide concerns event payloads, not inputs.

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

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

States a specific verb and resource ('Get a card's activity log') and enumerates exactly which events it covers (column moves, board moves, priority changes, assignee changes), which lets an agent distinguish it from siblings like get_board_activity or get_card_detail.

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

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

Gives a clear use case — 'answering when something moved or who changed it' — which frames the question this tool answers. It stops short of naming alternatives or exclusions (e.g., when to prefer get_board_activity), so it is clear context without 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?

Adds behaviour annotations don't cover: activity events are capped at the newest 100 and returned oldest-first, and the call is a single authorised round-trip. Annotations already declare readOnlyHint/openWorldHint=false, so the remaining gap (what happens if the card ID is invalid) is minor.

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, both earning their place: the first front-loads the returned contents, the second front-loads the steering decision. No restatement of the title or 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?

With an output schema present, return values need not be explained, and the description still previews the payload shape and the ordering/limit caveat on activity. For a one-parameter read tool whose safety profile is already in annotations, nothing an agent needs 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 card_id ('card UUID') is fully documented there; the description adds no syntax or format detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting for a single required 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?

Specific verb+resource (get a card) plus an explicit enumeration of the payload it aggregates: comments, activity events, checklist, attachments, GitHub PRs and branches. This clearly distinguishes it from get_card and the individual sibling fetchers.

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

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

States an explicit preference rule and names the four/five alternative tools it replaces (get_card, get_comments, get_card_activity, get_checklist, list_attachments), with the rationale of one authorised round-trip. An agent can route without 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context: the exact Markdown brief contents, the limit of '10 newest comments', attachment names only, and parity with the UI's 'Copy as prompt' action.

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 output format, followed by the UI parity and use case. Every part of the list and the two following sentences earns its place by clarifying what the brief contains and when to use 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 that an output schema exists, the description needn't document return structure, and it nevertheless describes the brief's contents in useful detail. For a single-parameter read-only tool, nothing important 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?

There is only one parameter, card_id, and the schema description coverage is 100% with the schema stating 'card UUID'. The description mentions working on 'a card' but adds no extra syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource ('Get a card') and precisely defines the output format as a 'ready-to-use Markdown brief'. It enumerates the fields included, which distinguishes it from generic card-fetching siblings like get_card or get_card_detail.

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

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

It explicitly says to use it 'to brief yourself or another agent on a card before working on it', giving clear when-to-use guidance. It does not name when-not-to-use conditions or alternative tools such as get_card_detail, so it falls 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered, and an output schema exists so return values need not be explained. The description adds only the ordering guarantee ('in position order'), which is minor but real added context beyond 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?

A single tight sentence with the resource and the ordering constraint front-loaded and no wasted words.

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 safety, an output schema covering the return shape, and the sole parameter fully documented, the definition is nearly sufficient for correct invocation. It could still note whether completed items are included or whether results are paginated.

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 there is a single required card_id parameter documented as 'card UUID'. The description adds no syntax or format detail beyond what the schema already provides, so the baseline of 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 (list a card's checklist items) plus the ordering guarantee, which is more than the title alone. It does not, however, differentiate itself from related siblings such as get_card_detail or get_card, which may also surface checklist data.

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 when-to-use guidance, no mention of when this is preferable to get_card_detail, and no prerequisites or exclusions. Usage is only inferable from the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds the sort order (oldest first), which is genuinely useful, but says nothing about pagination, result caps, or the non-idempotent behavior implied by idempotentHint=false on a list endpoint.

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 tight sentence with the resource and the ordering constraint front-loaded. Nothing is padded or repeated from the title.

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

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

An output schema exists, so return shape need not be described, and one fully documented required parameter keeps the call surface trivial. The only real omission is guidance on large comment threads (pagination or truncation), which matters somewhat for a list endpoint marked non-idempotent.

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% for the single card_id parameter ('card UUID'), so the schema already carries the semantics. The description adds nothing about the identifier beyond what the schema states, which is the expected baseline here.

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 (list) and resource (comments) scoped to a card, plus the ordering (oldest first). It is clearly distinguishable from add_comment/update_comment/delete_comment, though it does not explicitly contrast itself with the broader get_card_activity 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?

Usage is implied by the name and scope — an agent can infer this is the read path for a card's comment thread — but there is no explicit statement of when to prefer it over get_card_activity or get_card_detail, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful content-level detail about what is surfaced (stale in-progress, ghost cards, stuck cards), but says nothing about ordering, aggregation scope, or freshness of the counters.

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 a three-part colon list; every clause earns its place and nothing is padded. Slightly dense parentheticals are the only cost.

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 parameters and a declared output schema, the description needn't document return values, and it gives enough scope to call the tool correctly. The one real gap is sibling routing against get_hygiene, which belongs to usage guidance.

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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate at the parameter level. The colon-separated breakdown instead clarifies output categories, which is a bonus.

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 ('Get') plus resource ('focus overview') and an explicit enumeration of what the overview contains (due cards, attention-worthy cards, hygiene counters). It distinguishes the tool from generic listers, but it never clarifies how it differs from the very similar sibling get_hygiene, which it partially overlaps.

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 never states when to use this rather than get_hygiene, get_board, or search_cards, nor any preconditions or exclusions. The triage-oriented content implies a use case, but the agent must infer it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a genuine behavioral fact beyond the annotations — the result is 'capped at 100' — which tells the agent to expect truncation. It omits pagination behavior, but an output schema exists to cover the return shape.

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, zero waste, and the relationship to get_focus is front-loaded before the cap detail. 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 single-parameter read tool with annotations covering safety and an output schema covering return values, the description is sufficient: it establishes the purpose, the sibling relationship, and the 100-item cap. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and the single 'category' parameter is fully enumerated in the schema (ghosts, stuck, mine_no_date). The description adds no syntax or format detail beyond the schema, so the baseline of 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 ('List the actual cards behind one of get_focus's hygiene counters') and explicitly differentiates itself from the sibling get_focus by role: counts vs. which ones. An agent can distinguish it from list_archived_cards, search_cards, and get_focus 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?

Explicitly routes between siblings: 'get_focus tells you how many need attention; this tells you which ones.' That names the alternative and the condition that selects this tool, leaving nothing 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 establish readOnlyHint=true, but the description goes well beyond them: the meaning of the enabled=false return, the mail-to-card conversion rules (SPF/DKIM must pass, sender must be a workspace member, otherwise silently dropped), and the ai_usage quota semantics including the fallback to standard cards past the Pro limit.

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 purpose is front-loaded in the first sentence, followed by access constraints and then behavioral caveats; every sentence carries non-redundant information. The single dense paragraph is somewhat run-on, 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?

An output schema exists, so return values need not be explained, yet the description still clarifies the two fields an agent would most likely misread (enabled=false as non-error, ai_usage quota). Combined with the access and routing constraints, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and there is only one parameter (project_id, documented as a project UUID in the schema). The description adds no further parameter semantics, so the baseline of 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 ('Get a board's email-to-card intake address') and immediately distinguishes itself from the sibling mutators enable/disable/update_inbound_email by being purely a retrieval. An agent can select it 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 preconditions ('Board admins on Pro boards only') and explicitly tells the agent that enabled=false with no address is a normal state rather than an error, which prevents misdiagnosis. It does not, however, name the alternative tools (update/enable/disable_inbound_email) for when the agent actually wants to change settings.

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 openWorldHint=false, so safety is covered. The description adds genuinely non-obvious context: that twoFactorEnabled only affects browser password sign-in and not tokens, and that certain settings are browser-only — behavior an agent could not derive from the schema or annotations.

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

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

Three short sentences, front-loaded with the core action and returned fields, followed by the caveat. No filler, though the second and third sentences cover overlapping ground (both concern browser-only settings) and could be merged.

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

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

An output schema exists, so the description need not describe return shapes; covering the one field with ambiguous semantics (twoFactorEnabled) is the right supplementary choice. For a zero-param read-only self-lookup, this is close to complete, with only the positive use-case 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?

Zero parameters, so the baseline is 4. The description does not need to explain inputs, and instead spends its words on a returned field's semantics, which is a reasonable use of the space rather than wasted effort.

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

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

States a specific verb and resource ('Get the current authenticated user's profile') and enumerates the returned fields, so an agent can tell this is an identity/self lookup distinct from the get_project/get_board/get_card family. It does not explicitly contrast with list_members or get_avatar, so it stops short of full sibling differentiation.

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

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

Usage is implied rather than stated: no 'use this when you need identity context' sentence and no named alternative. What it does provide is a negative boundary — 2FA, password and API key changes can only be made in the browser, so point the user to Settings — which steers the agent away from attempting those mutations, but the positive 'when to call' case 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context — the payload is deliberately shallow (no cards) and results are scoped to "your role," implying permission-filtered output. It stops short of noting whether a missing project errors or returns empty, and idempotentHint=false on a pure read is left unexplained.

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 the verb and resource, then the returned fields, then the exclusion. 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?

With an output schema present, return values needn't be spelled out, and the description still sketches the payload shape. The only real gap is disambiguation from get_board, which matters given how many board-scoped siblings exist.

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?

There is a single parameter, project_id, fully documented in the schema as a project UUID. The description adds nothing about format or lookup semantics beyond that, so the schema carries the load — baseline 4 applies for a one-param tool at 100% coverage.

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

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

States a specific verb and resource ("Get one project") and enumerates what comes back: columns, counts, brief, and the caller's role. However, the sibling list contains both get_board and get_project, and the description never distinguishes them — the title even calls it "a board's settings," which muddies the noun rather than clarifying it.

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?

"Without loading every card" implies this is the lightweight path versus heavier reads like get_card_detail or export_project, but no alternative is named and there is no explicit when-not guidance. The agent must infer the routing from a trailing clause.

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, idempotentHint=true, and destructiveHint=true; the description adds real context beyond them by spelling out the in-place update semantics ('calling it again with a different role updates the grant in place') and the permission requirement (board admins only). It does not discuss whether the target user is notified or what happens if the user is not yet a workspace member.

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

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

Two sentences, front-loaded with the primary action and followed by the constraint and update semantics. Every clause carries information, though the parenthetical about re-calling is slightly verbose relative to its 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?

For a 3-parameter mutation with an output schema and full annotation coverage, the description supplies the auth requirement, the scope restriction, and idempotent-update behavior. It omits side effects such as notifications to the granted user, which is a minor gap rather than a blocking 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 100%, with the role enum values ('admin' vs 'contributor') already documented in the schema, so the baseline is 3. The description only references role changes generically and adds no format or constraint detail 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 ('Give a workspace member access to a specific board') plus a second behavior (updating the role of an existing grant). An agent can distinguish this from revoke_board_access, update_member_role, and invite_member 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?

Explicitly states the prerequisite ('Board admins only') and the when-not condition ('Only meaningful for workspace member role users - owners and admins already see every board'), which prevents wasted calls. It does not name the sibling to use instead for removal (revoke_board_access), so it falls just 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 past the annotations: side effects (new private board, never mutates an existing board), quota behavior with the concrete 402 failure, assignee-matching by email/username with matched people gaining board access and unmatched cards landing unassigned, and the fact that no notifications are sent. Hard limits (5 MB, 2,000 cards, 200 columns) are stated up front rather than discovered on failure.

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?

Purpose is front-loaded in sentence one, the mandatory preview step follows, and the remaining sentences are pure operational facts (quota, assignee matching, notifications, limits) with no filler or restated title.

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

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

For a non-idempotent, multi-format write tool with an output schema present, the description supplies everything an agent needs before calling: required precondition, quota failure mode, access side effects, notification behavior and payload limits. Nothing material is left to guesswork.

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

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

Schema description coverage is 100%, so the schema already documents filename, source, content_text/content_base64, mapping and name. The description reinforces the inline-file mode and size ceiling but adds no per-parameter semantics beyond that, 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?

Opens with a specific verb+resource ("Create a new board") and enumerates the accepted source formats (Trello JSON, Jira/Asana CSV, plain CSV, craaft JSON). It also states the output scope ("always creates a new private board"), which separates it from preview_import and from update_project-style siblings.

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

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

Explicitly routes the agent: "Call preview_import with the same arguments first and check the result with the user", naming both the alternative tool and the invocation condition. It also covers the cannot-do case ("never writes into an existing one"), so the agent knows when to reach for a different tool.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, idempotentHint=false), so the description carries real weight here: it discloses the immediate-vs-deferred consumption semantics, atomic board-grant application on accept, the permission requirement, and the 402 failure mode for Free workspaces. That is substantial behavioral context beyond 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?

Five short sentences, front-loaded with the core action, then progressively less obvious details (consumption timing, atomicity, permissions, plan gating). Every sentence adds a fact an agent needs; nothing 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?

An output schema exists, so return values need no explanation, and the description covers the mutation's side effects, timing, auth requirements, and the notable error case. For a 3-parameter mutation tool this 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 100%, so the baseline is 3, but the description adds genuine meaning by explaining when board grants take effect ('applied atomically on accept') and the account-state dependency of the invitation. It does not restate the role enum or board-grant shape, which 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 ('Invite someone to the workspace by email') and its scope is unambiguous against siblings like add_comment or grant_board_access. An agent can distinguish it from list_invitations, revoke_invitation, and grant_board_access without opening any schema.

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

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

Gives explicit preconditions (workspace owners and admins only; Pro plan required, Free returns 402) so the agent knows when the call will succeed. It does not, however, route to alternatives such as grant_board_access for an existing member or revoke_invitation to undo, leaving that inference to the agent.

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

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

Annotations already cover the read-only/idempotency profile, and the description goes further with non-structured behavior: ordering (most recently archived first), a hard result cap of 200, and notably that an inaccessible board yields an empty list instead of an error. That empty-list behavior is exactly the kind of detail an agent cannot derive from annotations or schema.

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, each carrying distinct information: purpose, ordering/cap, return shape, fallback route, and error behavior. Nothing is repeated from the title, and the most decision-relevant facts (ordering, cap, fallback) are front-loaded.

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

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

With an output schema present, the description need not enumerate return fields, yet it still flags the lean shape plus archivedAt so the agent can reason about results. Combined with coverage of cap, ordering, fallback to search_cards, and error semantics for a single-parameter read tool, nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% for the single project_id parameter, so the schema already carries the semantics. The description's phrase 'a board's archived cards' loosely implies project_id identifies the board but adds no format or constraint detail beyond the schema, 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 (List) plus resource (a board's archived cards) and adds ordering and cap as scope qualifiers. It names the sibling route (search_cards) for the case this tool cannot serve, so an agent can distinguish it from get_board and search_cards 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?

Explicitly routes the agent to search_cards when archived cards fall beyond the 200 cap, which is a concrete when-to-use alternative. It does not, however, state when not to use this tool at all (e.g. use get_board for live cards), so the guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the returned field list (name, size, content type, uploader), a mild addition, but with an output schema present this is largely redundant and no pagination or ordering behavior is disclosed.

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 efficient sentence that front-loads the core action and appends the field list. No waste, though the parenthetical return-field detail is partly redundant given the output 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?

With an output schema documenting returns, one fully-described parameter, and annotations covering the safety profile, the description is complete enough to invoke correctly. Only the absence of any routing guidance to sibling tools is a gap.

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

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

Schema description coverage is 100% with a single well-documented card_id. The description adds no extra semantics about the parameter beyond what the schema provides, so the baseline of 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 ('List the files attached to a card') that clearly scopes it to card-level attachments, distinguishing it from the sibling list_board_files. It is clear but never explicitly names a sibling or alternative to sharpen the contrast.

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 or mention of alternatives such as list_board_files or get_card, which could also surface attachment context. Usage is only implied by the tool 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 only declare the safety profile (readOnly/openWorld/idempotent), while the description adds real behavioral context: newest-first ordering, archived cards included, that each file is returned with its card, and that total counts all matches across pages while before/nextBefore drives pagination. These are traits an agent cannot derive from the annotations or schema.

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

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

Front-loaded with the core action and ordering, then filtering semantics, then pagination, then the follow-on tool. Four compact sentences, no repetition of schema text and 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 an output schema present, return shape need not be described. Combined with the annotations covering safety, the description supplies everything else an agent needs: scope, ordering, archived inclusion, filter semantics, and pagination continuation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the per-parameter text by explaining that query is case-insensitive AND-matched across file name, card title, card description, uploader name and content type, and by clarifying that total counts every match rather than the page size. The limit default/max adds nothing 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 ('List every file attached to cards on a board') plus scope qualifiers (newest first, archived cards included, card each one is on) that clearly separate it from siblings like list_attachments or get_card. An agent can identify the tool 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 routes the agent onward to download_attachment with the id when file contents are needed, and explains the paging flow (pass nextBefore back as before). It never states the inverse condition — when a per-card listing or list_attachments would be preferred — 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: that access can be either an explicit grant or implied by workspace role, telling the agent that membership is a derived, mixed-provenance concept.

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

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

Two tight sentences with no filler; the second sentence front-loads the 'source' semantics that matter most for interpreting rows. Slightly redundant against the existing output schema, 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 single-parameter read-only listing with an output schema present, the description covers purpose plus the one non-obvious field semantic ('source'). Nothing critical an agent needs to call it correctly is missing, though prerequisites (permissions required to view the roster) are 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?

Only one parameter (project_id) with 100% schema description coverage, so the schema already carries the burden. The description adds no syntax or format detail beyond implying the input identifies a board; baseline 3 applies when schema coverage is complete.

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?

"List who can see a specific board" gives a concrete verb+resource and a clear scope (board-level access), which implicitly separates it from the workspace-level list_members sibling. It never names an alternative explicitly, so sibling differentiation is left to inference 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?

The scope phrase "a specific board" implies the usage context (board-level access enumeration vs a workspace member list), but there is no explicit when-to-use/when-not statement and no mention of adjacent tools such as list_members or get_board.

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=true and openWorldHint=false, which the description reinforces by stating 'any authenticated user, no plan gate' (auth is not required beyond login, and there's no plan gating). It adds a valuable behavioral warning: only the default 'kanban' template seeds todo/doing/done keys, and other templates' keys are not exposed here. This is a non-obvious constraint that the agent needs. However, it doesn't discuss caching or other subtle behaviors, so it's 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 sentences that are front-loaded with the core purpose and then add essential usage and behavioral notes. Every sentence earns its place, though the parenthetical list of template names is slightly verbose. Still well-structured for a tool definition.

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

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

Given the tool is a simple read-only list with no parameters and an output schema, the description completes the picture by explaining the fixed nature of the data, the exact usage pattern (template argument on create_project), and the important caveat about column keys. An agent has everything needed to invoke and interpret the tool correctly.

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

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

There are zero parameters, so the baseline is 4. The description doesn't need to explain parameters, but it does explain the data returned and how to use it (via the template argument on create_project), which adds value 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 (List) and resource (fixed catalogue of board templates), and immediately distinguishes itself from mutable project data by noting it's 'the same for every caller.' The mention of specific template names (kanban, sprint, bug tracker) makes the purpose 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?

Explicitly tells the agent when to use it: pass a template's key as the template argument on create_project. It also implicitly covers when not to use it—there's no filtering or mutation here, just enumeration. The routing to create_project is precise.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful filtering context that only unaccepted invitations are returned, but says nothing about pagination, ordering, or volume, which matters for a list endpoint on a large workspace.

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 the verb and resource, and every clause earns its place by scoping the result set. No filler, no restatement of the title.

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

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

With an output schema present and no input parameters, the description need not explain return values. It is sufficient for correct invocation, though it could mention the invitation lifecycle tools (invite_member, revoke_invitation) to fully orient the agent.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The sentence does confirm the implicit filter (pending only) that an agent might otherwise assume is configurable.

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

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

States a specific verb and resource ('List pending workspace invitations') and narrows the scope with 'that haven't been accepted yet', which cleanly separates it from invite_member and revoke_invitation. It stops short of naming those siblings, so it lands at clear rather than maximally differentiated.

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 'pending / not yet accepted' qualifier implies when the tool is relevant, but there is no explicit when-to-use or when-not-to-use guidance and no pointer to the related invite_member or revoke_invitation tools. Usage is inferable, 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds real value beyond them: the phrase 'where visible' discloses that board visibility is permission-scoped and may be omitted for some members. Pagination and authorization requirements are not mentioned.

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 the resource and immediately qualified by what is returned. Every clause carries information and there is no filler.

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

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

With an output schema present, the description need not explain return values, and with no parameters and read-only annotations there is little behavioral surface left. It is nearly complete, lacking only notes on result size/pagination and permission requirements for the caller.

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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to compensate for; it correctly avoids inventing filter options the schema does not support.

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 and resource ('List workspace members') and enriches it with what is returned (roles, board visibility), which distinguishes it from the board-scoped sibling list_board_members. It stops short of naming that sibling explicitly, so an agent must infer the workspace-vs-board scope distinction.

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 only implied: the mention of roles and board visibility suggests an access-review use case, but there is no statement of when to call this rather than list_board_members or get_me, and no prerequisites. No exclusions or alternatives are given.

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 openWorldHint=false, so the safety profile is covered. The description adds one genuinely behavioral detail beyond that: results are ordered earliest due date first. It says nothing about pagination limits or result size.

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 zero waste: resource, scope, and ordering all in one clause. Every word 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 one-parameter read-only list tool with an output schema (so return values need no explanation) and annotations covering safety, the description is nearly sufficient. Only pagination/limits and usage routing to siblings are 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?

Only one parameter (project_id) with 100% schema description coverage ('project UUID'), so the schema carries the semantics. The description adds no extra meaning about identifier format or scope beyond what the schema states.

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

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

States a specific verb (List) and resource (milestones) scoped to a board, and adds the sort order. It is clearly distinguishable from add_milestone, update_milestone, and delete_milestone, though it does not explicitly name any 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?

No when-to-use or when-not-to-use guidance, and no mention of alternatives such as get_board or list_projects. The read-only listing intent is only implied by the verb 'List'.

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

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

Annotations already declare this is a read-only, closed-world, non-idempotent operation, but the description adds substantial behavior beyond that: unread comment/moved/updated rows are merged into a group row, the response includes an unseen badge count, and retention differs for read (90 days) versus unread (180 days). These details materially affect how an agent interprets results.

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

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

The description is dense and front-loaded with the primary purpose before pagination and return details. Some return-field explanation is arguably redundant because an output schema exists, but most of the length carries non-obvious behavioral 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 paginated notification-list tool with grouping behavior, retention rules, and an output schema, the description covers the important usage, cursor, filtering, and lifecycle context. Nothing essential for correct invocation or interpretation appears to be missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds useful semantics for before (it is the nextBefore cursor) and for kind=mention (the resulting row shape and commentId), though limit and unread_only are left to the schema.

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

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

The description states a specific verb and resource ('List your in-app notifications'), defines scope ('newest first'), enumerates included notification types, and distinguishes this from sibling tools such as mark_notifications_read. An agent can tell what this tool returns and when it is the right listing tool 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 explicit operational guidance: use nextBefore as before for the next page, use mark_notifications_read to mark rows read, and pass kind=mention to list mentions. These explicit alternatives and cursor instructions leave little to inference.

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