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

The description is consistent with the annotations (readOnlyHint=false aligns with 'Add...'). It adds content-type constraints (emojis, short text, max 16 characters) and the lightweight-response framing. However, the annotations are minimal, and the description does not disclose repetition behavior (what happens if the same reaction is added twice), permission needs, or return value, leaving some behavioral gaps for a mutation tool.

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

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

Three short sentences with the action verb front-loaded. The second sentence on content format partially repeats what the schema's content property already states, which is minor waste, but overall the definition is efficiently sized and readable at a glance.

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

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

For a simple, well-documented action (4 required params, all clearly described in schema, no output schema), the description covers the purpose and use case adequately. The schema handles parameter semantics, so the only real gaps are unstated idempotency behavior and return-value expectations, which are minor for a lightweight write action.

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% — every parameter (content, comment_id, card_number, account_slug) has a detailed schema description including formats and examples. The tool description largely duplicates the schema's content details (emoji examples and the 16-character limit). With full schema coverage, the baseline of 3 applies; the description adds no new parametric meaning.

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

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

The description opens with a specific verb+resource construction: 'Add an emoji reaction to a comment.' It clealy distinguishes this from sibling tools like fizzy_remove_reaction (removal) and fizzy_create_comment by framing reactions as 'quick... responses without writing a full reply.' The scope is precise and no ambiguity remains about what operation this performs.

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

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

'Use this to quickly acknowledge or respond to comments without writing a full reply' provides a clear context for when the tool applies. It implies when-not-to-use (when a substantive reply is warranted) but never names alternative tools explicitly, so an agent must infer that fizzy_create_comment is the fallback.

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

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

The description adds behavior beyond the annotations by stating that closed cards are 'archived and removed from active view'. This clarifies the tool's side effects in a way the readOnlyHint and destructiveHint do not fully capture. It does not contradict the annotations, since 'archived' implies retention rather than destruction.

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

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

The description is two concise sentences with no unnecessary words. It leads with the core action and result, then provides usage context. Every sentence earns its place.

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

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

For a simple mutation tool with no output schema, the description covers the core behavior, result, and when to use it. It does not mention reversibility or relationship to fizzy_reopen_card, but the core information an agent needs to select and call it is present.

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

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

Schema description coverage is 100%, and both 'account_slug' and 'card_numbr' have detailed descriptions in the schema. The tool description does not add parameter-specific semantics, 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 states a specific verb ('Close'), a resource ('a card'), and the resulting state ('mark it as done/completed', 'archived and removed from active view'). This clearly distinguishes the action from sibling tools like fizzy_delete_card and fizzy_reopen_card.

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

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

The description gives an explicit trigger condition: 'Use this when work on a card is finished.' This provides clear context for when to invoke the tool, though it does not explicitly mention alternatives or state when not to use it, such as when deletion is intended.

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 signal that this is a non-read-only, non-destructive operation. The description adds useful behavioral context by stating that the newly created board is returned with its ID and URL, which is especially valuable given there is no output schema to convey this.

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

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

The description is compact and every sentence earns its place: it states the action, explains the conceptual role of boards, and notes the return value. No filler or redundancy is present.

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

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

For a simple two-parameter create operation, the description is largely complete: all parameters are documented in the schema, the return value is described due to the absent output schema, and annotations cover the safety profile. It does not discuss error cases or idempotency, but those are not essential for this straightforward creation tool.

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

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

Schema description coverage is 100%, and both parameters are already well documented; account_slug even includes examples and guidance on where to obtain valid values. The tool description itself adds no additional parameter semantics, so the baseline score 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 uses a specific verb and resource combination: 'Create a new board in a Fizzy account.' It also clarifies that boards are top-level containers for organizing cards, which distinguishes this tool from create_card and create_column without needing to read the schema.

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

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

The description implies when to use the tool through the context that boards are top-level containers, but it never explicitly states when to choose this over alternatives or mentions any prerequisites beyond the account slug. Since no alternative create-board sibling exists, the lack of exclusions is somewhat mitigated, but the guidance is still 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?

Annotations (readOnlyHint=false, destructiveHint=false) already establish that this is a mutating but non-destructive operation, and the description adds the triage-default placement behavior and HTML support for descriptions. However, most behavioral detail — draft/published visibilty, assignment notifications, and the 'assignment_warnings' fallback — lives in the schema rather than the description. No contradiction with annotations; modest added 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?

Two sentences, zero waste. The first sentence front-loads the verb, resource, and field list; the second conveys the key default behavior. 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 9-parameter creation tool with no output schema, the description covers the essentials (what it creates, what fields are optional, the triage default) while the 100%-coverage schema supplies all parameter semantics. The only gap is that nothing states what the successful response contains, but for a create tool with no output schema this is a minor omission.

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 structured data fully documents all 9 parameters. The description merely lists field names ('status (draft/published), column placement, assignees, tags, and due date') without adding syntax, formats, or semantics beyond what the schema already 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?

The description uses a specific verb+resource construction — 'Create a new card on a board' — and enumerates the optional fields (title, description, status, column placement, assignees, tags, due date). This is unmistakably distinct from sibling card tools like update_card, close_card, or move_card_to_column.

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

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

The description implies the usage scenario (creating new cards) and adds one useful behavioral default: 'Cards start in triage by default unless a column is specified.' However, it never explicitly tells the agent when not to use this tool or names alternatives such as fizzy_update_card for modifying existing cards. The schema compensates somewhat by pointing to fizzy_get_boards and fizzy_get_identity/fizzy_get_accounts for prerequisites, but the description itself gives only implied 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 indicate this is a mutating, non-destructive operation. The description adds domain context ('Columns define workflow stages and help organize cards through your process') but does not disclose additional behavioral traits such as response behavior, duplicate handling, or permission requirements. No contradiction with annotations exists.

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

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

The description is concise and front-loaded with the action. The color list is somewhat redundant with the schema enum, and the domain context sentence adds value but is not strictly necessary. Overall, it earns its place without being verbose.

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

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

Given the rich schema with full parameter descriptions, the clear annotations, and the straightforward nature of a create-column operation, the description provides enough context for an agent to select and invoke the tool correctly. It clearly states what the tool does and how columns fit into the workflow model.

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 each parameter, including name, color, board_id, and account_slug, is well-documented in the schema. The description redundantly lists colors but does not add meaning beyond what the schema already provides, so the baseline score 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?

The description clearly states a specific action and resource: 'Create a new workflow column on a board with specified name and color.' It distinguishes this from siblings like fizzy_update_column, fizzy_delete_column, and fizzy_get_columns by emphasizing creation of a new column and its role as a workflow stage.

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

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

The description gives clear context for when this tool is appropriate: when a new workflow column needs to be created on a board. It does not explicitly name alternatives or when-not-to-use conditions, but the create-vs-read/update/delete distinction is implicit and clear from the phrasing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, establishing this as a safe, non-destructive write operation, and the description is consistent with that. The description adds the HTML formatting capability as a behavioral feature, which is genuinely useful. However, it does not disclose what happens on success (e.g., whether the comment object is returned), whether the operation is idempotent, or any authentication/permission requirements. With annotations covering the safety profile, this is adequate but not rich.

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

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

The description is efficiently structured: the core purpose is front-loaded in the first sentence, followed by the HTML formatting detail, then the usage context. Every sentence earns its place. Minor deduction because 'Use this to provide feedback or updates on cards' is somewhat redundant with 'Add a new comment,' which already implies feedback conveyance. Otherwise, no waste.

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

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

For a 4-parameter mutation tool with no output schema, the combination of a rich schema (100% param coverage, mutual-exclusivity guidance for card_id/card_number, examples) and annotations (safe mutation) covers most operational needs. The description adds the HTML formatting behavior and the intended use case. The only gap is the absence of expected return behavior on success, but the schema carries most of the contextual weight here.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the tool description itself says nothing about parameters. The parameter descriptions in the schema are excellent: body lists all supported HTML tags, card_id explains the numeric ID with an example, card_number differentiates from card_id, and account_slug explains how to obtain valid values. The tool description adds no parameter meaning beyond the schema, so the baseline score is appropriate.

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

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

The description states a specific verb and resource: 'Add a new comment to a card.' The word 'new' semantically differentiates it from siblings like fizzy_update_comment, fizzy_delete_comment, fizzy_get_comment, and fizzy_get_card_comments without needing to open any of their schemas. The use case ('provide feedback or updates on cards') reinforces the purpose.

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

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

The description provides clear usage context: 'Use this to provide feedback or updates on cards.' This tells the agent when this tool is appropriate. However, it does not name explicit alternatives or exclusions (e.g., 'use update_comment to modify an existing comment' or 'use get_card_comments to read existing comments'), so the agent must infer sibling differentiation from names alone.

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

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

Annotations already indicate this is a non-read-only, non-destructive mutation. The description adds meaningful behavioral context by stating that new steps are 'created as incomplete by default,' which is not visible in 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?

The description is short and front-loaded with the core purpose. The phrase 'Steps help break down work into manageable tasks' is slightly filler, but the rest is efficient and the default-incomplete detail is valuable.

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

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

For a simple create operation with three fully documented required parameters and annotations covering the safety profile, the description is largely complete. It could mention what happens on success, but the absence of an output schema makes that a minor gap.

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

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

Schema description coverage is 100%, and the schema already provides detailed parameter descriptions, including examples for content and guidance for card_number and account_slug. The tool description adds no additional parameter-specific meaning, 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 clearly states a specific action ('Create a new to-do step'), identifies the resource ('checklist item on a card'), and differentiates it from sibling tools like fizzy_get_step, fizzy_update_step, and fizzy_delete_step. The scope 'on a card' adds useful precision.

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 guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., the card must exist), and no exclusions. The use case is only implied by the word 'Create'.

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 the description adds meaningful context by specifying the impact: access is revoked and the operation is significant. This goes beyond the bare annotation and helps an agent understand the severity, though it does not address reversibility or side effects on related resources.

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

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

Two short sentences with no filler. The core action and consequence are front-loaded, followed by a clear caution. Every sentence contributes 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 simple two-parameter destructive operation, the description plus annotations cover the action, severity, and parameter sourcing. The main gap is the lack of any statement about reversibility or what happens to the user's data after deactivation, but the destructive annotation and caution provide sufficient safety context.

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 already include useful detail about where to obtain them (fizzy_get_users, fizzy_get_identity, fizzy_get_accounts). The description itself adds no further parameter-level meaning, 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?

The description states a specific action ('Deactivate a user account') and a concrete consequence ('revoking their access'), making it clear this is the tool for deactivating a user. It reads distinctly from sibling tools like fizzy_get_user and fizzy_update_user, so an agent can identify its role 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?

The description warns to use caution and notes the operation is significant, but it does not say when to prefer this tool over alternatives, whether it is reversible, or what prerequisites might exist. There is no explicit guidance about when it should be used versus fizzy_update_user or other user-management tools.

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

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

Annotations already mark the operation as destructive, and the description adds valuable detail beyond that: it explicitly says the deletion cannot be undone and enumerates what will be destroyed (cards, columns, associated data). This gives an agent a clear mental model of the operation's consequences.

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 short and front-loaded, with the destructive scope stated in the first sentence. 'Use with caution' is mildly redundant after 'cannot be undone,' but overall the text is tight and effective.

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

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

For a simple destructive action with two fully documented parameters, the description provides all essential context: the operation is permanent, widespread in scope, and should be treated carefully. No output schema exists, but for a delete operation this omission is not a meaningful gap.

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

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

Schema coverage is 100% and the schema itself provides detailed parameter descriptions, including formats, examples, and how to obtain valid values via fizzy_get_boards, fizzy_get_identity, or fizzy_get_accounts. The description adds no new parameter-level 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?

The description uses a specific verb/resource pair — 'Permanently delete a board' — and expands on scope by naming what is removed: cards, columns, and associated data. This clearly distinguishes it from sibling delete tools such as fizzy_delete_card or fizzy_delete_column.

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 intended use is implied: choose this when you want to permanently remove an entire board. However, the description does not explicitly state when to use it versus alternatives, nor does it mention exclusions such as preserving any of the board's contents.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds materially more: the exact blast radius (comments, steps, and attachments are destroyed) and irreversibility ('cannot be undone'). For a destructive operation this is precisely the behavioral context an agent needs before invoking. No contradiction with annotations.

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

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

Two sentences (~25 words) with zero waste: the action and blast radius are front-loaded, followed by a one-sentence irreversibility warning. 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?

The description is complete for selecting and invoking a simple destructive tool: it states the operation, consequences, and irreversibility, with both parameters documented in the schema. Minor gaps: no output schema so return/confirmation behavior is unstated, and the card_id ambiguity in the schema goes uncorrected.

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 card_id schema description is self-contradictory: the property is named card_id yet the text says 'This is different from card_id' and conflates the visible card number ('#123') with the internal ID, which can mislead an agent on what value to pass. The tool description adds no clarification; only account_slug is well-documented.

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

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

States a specific verb ('permanently delete'), resource (card), and scope ('all its contents including comments, steps, and attachments'), which clearly conveys the operation and implicitly separates it from partial-delete siblings like fizzy_delete_comment and fizzy_delete_step. It does not explicitly name a sibling to distinguish from, so it falls just short of a 5.

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

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

The destructive warning ('cannot be undone') implies this is for permanent removal rather than temporary state changes like fizzy_close_card, and the scope implies whole-card removal vs. deleting individual comments or steps. However, no explicit when-to-use, when-not-to-use, or alternative tools are named, leaving routing to inference.

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

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

While the annotations already set destructiveHint to true, the description adds concrete behavioral detail beyond that flag: it explains that cards in the column will be moved to triage and that the operation 'cannot be undone.' This gives an agent a clear picture of the side effects and permanence, which is exactly the kind of context destructive operations need.

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 three terse sentences: the core action, the side effect, and the explicit warning about irreversibility. Every sentence contributes needed information and the most important fact is front-loaded, with no filler or redundancy.

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

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

All three required parameters are fully documented in the schema, the annotations mark the operation destructive, and the description adds the crucial behavioral consequence of moving cards to triage and irreversible deletion. For a delete operation with this level of schema and annotation support, an agent has enough information to correctly select and invoke the tool.

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

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

The schema descriptions already cover 100% of the parameters, providing examples and telling the agent where to obtain valid IDs from sibling tools like fizzy_get_boards, fizzy_get_columns, and fizzy_get_identity. The tool description itself adds no parameter-level details, but because the schema is rich, the baseline score 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 begins with 'Permanently delete a workflow column from a board,' which names the specific verb, target resource, and scope. The added consequence that cards are moved to triage further clarifies what this operation does and distinguishes it from sibling deletion tools like fizzy_delete_board, fizzy_delete_card, and fizzy_delete_comment.

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

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

The description clearly implies the intended use case—deleting a workflow column—but does not explicitly state when to use it versus alternatives or when not to use it. It does note the behavioral consequence (cards moved to triage), which gives helpful context, but it never references sibling tools such as fizzy_update_column or fizzy_move_card_to_column.

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?

Although annotations already declare destructiveHint=true, the description adds meaningful behavioral context beyond that: the deletion is permanent, cannot be undone, and is restricted to the comment author. This enriches the agent's understanding without contradicting 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?

The description is two sentences with no wasted words. The destructive, permanent nature is front-loaded with a warning icon, followed by the critical author-permission constraint. Every sentence earns its place.

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

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

Given the complete parameter schema, the destructive annotation, and the description's added irreversibility and permission details, the description fully covers what an agent needs to correctly invoke this tool. No output schema exists, so return-value explanation is not required.

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 all three required parameters well documented in the input schema. The description itself does not add parameter-level detail beyond what the schema already provides, so a baseline score 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 uses a specific verb and resource: "Permanently delete a comment from a card." It clearly distinguishes the operation from sibling tools like fizzy_get_comment, fizzy_create_comment, and fizzy_update_comment, leaving no ambiguity about the tool's function.

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 provides clear context that this is a destructive delete operation and adds an important restriction: only the comment author can delete their own comments. It does not explicitly discuss alternatives, but the permission constraint and destructive nature provide enough guidance for appropriate use.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds value by clarifying the deletion is permanent and irreversible. It also scopes the destructive behavior to 'a to-do step from a card,' which is useful beyond the structured metadata. No contradiction exists.

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

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

The description is extremely efficient: one sentence states the purpose, and one short sentence delivers a high-signal irreversible warning. Every word earns its place and the destructive caveat is front-loaded enough to be noticed.

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?

All required parameters are documented in the schema, the destructive/irreversible nature is explicit, and the object being deleted is clearly identified. It doesn't describe the success response or post-conditions, but for a simple delete operation with no output schema that is a minor gap rather than a functional deficiency.

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

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

The schema description coverage is 100%, so the three required parameters are fully documented there. The tool description itself adds no parameter-level detail, but that is acceptable because the schema already carries the full semantic burden, giving the baseline score of 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?

The description states a specific action, 'permanently delete', and a specific resource, 'a to-do step from a card'. It clearly distinguishes this from update_step, create_step, and other delete tools for different objects, and the 'cannot be undone' phrasing prevents confusion with soft-close or archive operations.

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

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

The description communicates that this tool is for permanent step removal, and the explicit destructive warning gives strong context for when it should be used cautiously. It doesn't name alternatives such as update_step for non-destructive changes, so it misses the explicit when-not/when-else guidance that would merit 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 destructiveHint=false, so the safety profile is clear. The description adds value by revealing output contents (slugs, names, access levels) and current-user scoping, which is useful because no output schema exists.

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

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

A single sentence that front-loads the action and scope before stating return details, with 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?

For a zero-parameter read-only listing tool with annotations covering safety, the description fully covers what the agent needs: what it returns, for whom, and what fields are included.

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 has zero parameters and schema coverage is 100%, so there is no parameter meaning for the description to add; this matches the baseline for parameterless tools.

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?

Description specifies the verb 'Get all' and a concrete resource (Fizzy accounts accessible to the current user), and enumerates returned fields (slugs, names, access levels), making it distinct from sibling account/board/user tools.

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

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

The phrase 'accessible to the current user' gives clear scoping for when to call this tool, and the resource name 'accounts' differentiates it from identity, board, card, and user tools. It does not explicitly name alternatives or exclusions, but none are necessary for this simple 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 mark it read-only and non-destructive; the description adds substantial behavior beyond that: media type classification, when bytes are not downloaded, when rendering is refused, and preview behavior. No contradictions with annotations.

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

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

Rich content earns its place: every sentence adds context or constraint. Slightly long, but each clause carries meaning about when/how to use or when not to use the tool; the key usage context is front-loaded after the first sentence.

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

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

For a 4-param read-only fetch tool with no output schema, it covers what the model sees, when bytes are not downloaded, which variation to request, where params come from, and the refusal case. An agent can invoke correctly without guessing.

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. The description adds real value by explaining where each parameter comes from (signed_id/filename from fizzy_get_card/comments with include_attachments=true), that variation should be omitted appropriately, and that URL/path construction won't work. This is more than the schema alone provides.

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

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

States a clear verb ('Fetch') and resource ('a file already attached to a card or comment'), then differentiates from siblings by explaining what comes back. It explicitly distinguishes itself from upload (fizzy_upload_file) and the card/comment list tools that expose attachment metadata.

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?

Goes far beyond a simple trigger: it tells the agent when to use it (any card/comment referencing a screenshot/mockup/diagram/error image where the answer depends on the image), what to prefer (preview_variation), and what not to do (do not build args from a URL by hand). This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the kind of information returned and its role in understanding board structure, but it does not disclose response shape details, error behavior, or any other operational quirks.

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

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

The description is two sentences with no filler. The core action and returned fields are upfront, and the usage guidance is immediately actionable.

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

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

For a simple read-only GET tool with two well-documented parameters, the description covers purpose, when to use it, and the general return contents. The lack of an output schema and exact metadata details prevents a perfect score, but the description is sufficient for correct selection and 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?

The input schema has 100% description coverage for both parameters, including examples and where to obtain valid values. The tool description itself adds no parameter-specific meaning, so the baseline score 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?

The description clearly identifies the operation as retrieving detailed information about a specific board, and lists key returned content (name, description, URL, metadata). It distinguishes itself from the plural sibling fizzy_get_boards by emphasizing 'specific board'.

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

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

The description gives concrete usage context: use this to understand board structure before querying cards or columns. It does not explicitly name alternative tools for different scenarios, such as fizzy_get_boards for listing boards, but the guidance is clear enough for an agent to know when this tool is appropriate.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: every upstream page is fetched server-side, there is no page parameter, and the result is a complete list. This goes beyond the annotations to set correct pagination expectations, though it omits rate-limit or performance details.

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 serving a distinct purpose: defining scope, listing return fields, and clarifying pagination behavior. Front-loaded and no filler; every sentence earns its place.

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

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

For a read-only list tool with one fully documented parameter and no output schema, the description covers scope, return fields, usage context, and completeness of results. Nothing an agent needs to invoke it correctly is missing.

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

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

The schema provides 100% coverage for the single parameter account_slug, including format examples and where to obtain valid values. The description does not add parameter-specific meaning 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 ('Get all boards in a Fizzy account') and lists the returned fields (IDs, names, descriptions, URLs). The plural 'all' clearly differentiates it from the sibling fizzy_get_board, and the title 'List Boards' reinforces the intent.

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

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

Explicitly instructs when to use this tool: 'discover available boards before working with cards.' This gives clear context for selection. It does not explicitly name alternatives like fizzy_get_board for single-board lookups, 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?

Annotations already declare read-only, and the description adds valuable behavioral nuance: attachments appear only as raw <action-text-attachment> markup, plain text flattens them to uninspectable filenames, and include_attachments=true is required to get structured metadata. It even discloses the default response behavior, leaving no ambiguity about side effects.

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

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

The description is front-loaded with the main purpose and usable context, then delivers a compact but necessary attachment warning. Every sentence carries information; the length is justified by a non-obvious worklow for attachment retrieval.

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

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

With no output schema, the description carries return-value exposition and does so thoroughly: it lists content categories, explains attachment shapes and default behavior, and gives a clear follow-up path. An agent has enough to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3; the description does add a small usage heuristic for include_attachments (pursue attachment data when visual content matters). The cardinal flaw is the card_id property: it says the parameter is a 'card number' and that 'This is different from card_id' even though the property is named card_id, creating confusion instead of clarity.

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 ('Get'), a specific resource ('a specific card'), and enumerates the returned content: full HTML description, assignees, tags, due dates, steps, and metadata. The description's attachment caveat is clearly tied to a detail-read operation, and the tool name further distinguishes it from the list-style fizzy_get_cards sibling.

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

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

Gives explicit context ('Use this to see complete card content before making updates') and names the follow-up alternative (fizzy_get_attachment) with a triggering condition ('whenever a card mentions a screenshot or the answer depends on what a picture shows'). It does not explicitly exclude list-style siblings such as fizzy_get_cards, so it stops short of full marks.

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 read-only annotations, the description discloses important behaviors: server-side fetching of every upstream page, no pagination parameter, comment text never being truncated, raw <action-text-attachment> markup behavior, and the effects of include_attachments. This gives the agent a clear model of what the operation does and what to expect in the response.

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

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

The description is front-loaded with the core purpose, then flows naturally into response behavior, fields projection, and attachment handling. Each sentence contributes new, actionable information without redundant filler, and the length is justified by the tool's complexity.

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

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

With no output schema, the description covers the key return contents (text, authors, timestamps, reaction counts), the complete-thread guarantee, the fields projection options, and the attachment retrieval workflow. It is sufficient for an agent to select and invoke the tool correctly with no lingering behavioral gaps.

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

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

Although schema coverage is 100%, the description adds meaningful parameter semantics: fields='summary' drops duplicated HTML and repeated card/creator detail, comment text remains untruncated, and include_attachments=true produces an attachments array with signed_id for use with fizzy_get_attachment. This goes well beyond the schema's baseline descriptions.

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

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

The description opens with a specific verb and resource: 'Get all comments on a card in chronological order.' It further clarifies the result scope by stating 'the complete thread... no page parameter and nothing further to request,' which differentiates it from single-comment tools like fizzy_get_comment.

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

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

The description gives clear usage context: 'Use this to review discussion and feedback on a card,' and explains the complete-thread behavior so an agent knows no pagination is needed. It provides guidance on when to use fields='summary' versus 'full' and how to retrieve attachments, though it does not explicitly state alternatives like fizzy_get_comment for fetching a single comment.

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

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

Annotations cover readOnly/destructive safety, so the description's job is behavioral nuance — and it delivers extensively: server-controlled variable page size, total_count meaning vs page length, out-of-range pages returning empty cards while has_more may stay true, search OR-matching and stemming, stopword dropping with ignored_search_terms, and fields='summary' payload reduction. No contradiction with the readOnlyHint=true annotation.

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?

Around 230 words covering a 10-parameter tool with real pagination traps. Every sentence earns its place: core action first, then filters, then search semantics, then pagination mechanics, then performance guidance and handoff. Nothing is fluff, and the density is justified by the operational traps it prevents.

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

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

With no output schema, the description fully carries the return-value burden and does so explicitly: returns {cards, page, total_count, has_more, next_page}, explains total_count semantics, and gives the exact enumeration loop ('call repeatedly with page = next_page until has_more is false OR cards comes back empty'). Complex tool, no gaps.

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

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

Schema coverage is 100%, so the baseline is 3 — the schema already documents every parameter thoroughly. The description adds value beyond the schema by wiring parameters to use cases (search_mode='all' for existence checks, fields='summary' for large scans, board_id sourced from fizzy_get_boards) and clarifying cross-parameter behavior, but it does not add per-parameter syntax details the schema lacks.

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 page of cards in an account') plus the full set of filter dimensions. It also explicitly distinguishes itself from fizzy_get_card ('call fizzy_get_card for its full detail'), so an agent can tell them apart without opening schemas.

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

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

Gives explicit when-to-use advice: fields='summary' when browsing/scannery many cards, search_mode='all' when checking whether a card already exists, and a clear handoff to fizzy_get_card once the specific card is identified. This is actionable routing guidance, not vague 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the specific information returned (name, color, position, card count) but does not disclose error behavior, auth requirements, or other runtime traits. With annotations carrying the safety burden, this is adequate but not rich.

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

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

A single front-loaded sentence with zero wasted words. It opens with the verb and resource, then lists the returned fields. 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 simple read-only operation, the definition is nearly complete: annotations cover safety, the schema documents all parameters and where to obtain them, and the description explains what the tool returns in lieu of an output schema. The only gap is the lack of an explicit pointer to fizzy_get_columns for list-style use cases, which is minor.

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 all three parameters already documented in detail including examples and pointers to source tools (e.g., 'Get available column IDs from fizzy_get_columns'). The description adds no parameter-level meaning 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?

The description states a specific verb (Get), a specific resource (a specific workflow column), and enumerates the returned attributes (name, color, position, card count). The word 'specific' combined with the singular name distinguishes it from the plural sibling fizzy_get_columns, but it never explicitly names that alternative, so the differentiation is implicit rather than explicit.

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 context is implied — an agent can infer this tool is for retrieving details about one column once a column_id is known, as opposed to listing columns. However, the description provides no explicit when-to-use/when-not-to-use guidance and does not point to fizzy_get_columns as the alternative for listing all columns.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that columns represent workflow stages and lists returned fields, which is useful, but it does not disclose additional behavioral traits such as pagination, authorization requirements, or any implicit ordering beyond 'positions.'

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

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

The description is two sentences with no redundant filler. It front-loads the primary action, adds domain context, and then states the return fields, with every sentence contributing 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 simple read-only list tool with two fully documented required parameters, the description is complete: it explains what the columns represent, the expected return contents, and the input context. There is no output schema, but the description adequately covers what an agent needs to know to invoke and interpret the result.

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 board_id and account_slug are already well-documented with examples and guidance on how to obtain valid values. The description adds no new parameter-level detail, 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?

The description uses a specific verb and resource: 'Get all workflow columns on a board,' which clearly distinguishes this from single-column tools like fizzy_get_column. It also states what is returned, removing any ambiguity about the tool's purpose.

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

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

The description clearly indicates this tool is for retrieving all workflow columns for a specific board, providing a clear context for use. It does not explicitly name alternatives or exclusions, such as 'use fizzy_get_column for a single column,' but the sibling set makes this reasonably inferable.

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 read-only and non-destructive behavior is already covered by annotations (readOnlyHint=true, destructiveHint=false). The description adds meaningful behavioral context by disclosing that the response includes full HTML content, author, timestamp, and reactions, which is especially valuable given there is no output schema. It does not discuss auth or rate limits, but that is not critical for a simple read 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?

The description is concise at under 30 words and front-loads the core purpose in the first sentence. The second sentence, 'Use this to read a specific comment in detail,' is mostly redundant with the first but does add a usage directive, introducing only minor repetition.

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

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

For a single-comment read tool with read-only annotations, the description adequately conveys purpose, return content, and usage intent. The absence of an output schema makes the return-field enumeration especially helpful. A small gap is the lack of explicit routing to get_card_comments for listing, but the schema already instructs how to obtain comment IDs.

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 each parameter is thoroughly documented with examples and sources (e.g., comment_id points to get_card_comments). The description adds no parameter-specific meaning beyond the schema, so the baseline score 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?

The description clearly identifies the action ('Get detailed information') and the resource ('a specific comment'), enumerating key output fields (full HTML content, author, timestamp, reactions). It does not explicitly name the sibling list tool gereal_comments, but the phrasing 'specific comment' and 'in detail' distinguishes it from a list operation.

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

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

Provides a clear usage directive: 'Use this to read a specific comment in detail.' This establishes when the tool is appropriate, though it doesn't explicitly mention alternatives or exclusion scenarios, such as pointing to get_card_comments for listing all comments.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful return-content detail (email, name, accounts with slugs and permissions), but does not disclose anything like authentication failure behavior or whether accounts may be empty. This is a modest value-add beyond annotations.

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

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

The description is a single, well-structured sentence that leads with the action and resource, then lists the key return fields. There is no redundancy or 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 zero-parameter, read-only identity tool with no output schema, the description is complete: it states what is returned and includes the important account/permission details. No essential information for calling the tool correctly is missing.

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

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

The input schema has zero parameters and 100% description coverage, so the baseline is 4. The description reinforces that no parameters are needed by framing the operation as identity retrieval, which is consistent with an empty 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 action ('Get') and a clearly defined resource: the current authenticated user's identity plus associated Fizzy accounts. It also distinguishes this from sibling tools by emphasizing 'current authenticated user' and the account list with slugs and permissions, which separates it from get_accounts/get_users.

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

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

The description makes it clear this tool is for retrieving the authenticated user's own identity, which gives the agent an obvious usage context. It does not explicitly name alternatives or exclusions, but for a zero-parameter identity tool the framing is sufficient.

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 mark the tool as read-only, and the description adds substantial behavioral detail: the default returns up to 100 unread plus recent read notifications, pages 2+ contain only older read notifications, page size is server-controlled and variable, and page length must not be used to infer counts or remaining history. This goes well beyond what annotations provide.

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

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

The description is front-loaded with the tool's purpose and then organizes pagination behavior and fields guidance in a logical order. It is longer than minimal, but every sentence carries operationally important information for correct paging and efficient response handling.

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

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

With no output schema, the description supplies enough return-shape information (notification content, read/unread status, timestamps, related cards/comments) and covers all parameter behavior, pagination edge cases, and the empty-array termination signal. The read-only safety is already captured by annotations, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mirrors the schema's page and fields explanations and adds only minor framing like 'what needs my attention' and 'typically several times smaller,' but it does not provide new parameter-level meaning.

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: 'Get notifications for the current user in an account,' and lists what is returned (notification content, read/unread status, timestamps, related cards/comments). This clearly distinguishes it from sibling tools that operate on boards, cards, or comments, even without naming them.

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

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

The description gives explicit use-case guidance: the default response is 'what you want for what needs my attention,' pages 2+ are for walking older history, and fields='summary' is recommended for scanning or listing. It does not explicitly name alternatives or when-not-to-use conditions, so it falls just short of a 5.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds valuable behavior beyond that: non-paginated, at most 100 pins, plain array return, and a warning about potentially several-megabyte payloads with default fields. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then covers constraints, performance, and alternatives in logical order. Every sentence adds actionable information; the length is justified by the value it provides.

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

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

For a read-only, non-paginated listing tool, the description covers return shape, limits, performance, field selection, and related tools. No output schema exists, but the description sufficiently explains what to expect without needing to document card object internals.

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 already documents both parameters fully (100% coverage), but the description adds meaning by strongly recommending fields='summary' and quantifying size differences (4x to over 100x smaller). It also clarifies account_slug format and how to discover valid slugs via fizzy_get_identity/fizzy_get_accounts.

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 cards the current user has pinned in an account, as a plain array of cards.' It clearly defines scope (per-user, per-account) and is easily distinguished from siblings like fizzy_pin_card and fizzy_get_card.

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 advises when to prefer fields='summary', tells the agent to call fizzy_get_card for full detail of a specific pin, and names fizzy_pin_card/fizzy_unpin_card as the tools for changing the list. This is direct when-to-use vs. alternative 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 destructiveHint=false, and the description adds value by disclosing the return shape (emoji or text content, authors, timestamps) — notably that reactions can be text, not just emoji. No contradiction exists; the 'Get' phrasing aligns with the read-only annotation.

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 with zero filler: the first states the operation, the second specifies the output, and the third gives the use case. The core action is front-loaded and every sentence earns its place.

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

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

For a simple read-only list tool, the combination of annotations (safety profile), 100% schema coverage (all three parameters documented), and a description that discloses return contents to compensate for the absent output schema is nearly complete. Only minor details like response ordering or pagination go undisclosed.

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 each parameter (account_slug, card_number, comment_id) already documented with format examples and provenance hints. The description itself adds no parameter-level 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?

The description uses a specific verb-resource pairing ('Get all emoji reactions on a comment') and names the return contents (reaction content, authors, timestamps), which clearly distinguishes it from reaction-mutation siblings like fizzy_add_reaction and fizzy_remove_reaction, and from comment-listing tools like fizzy_get_card_comments.

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?

'Use this to see how team members respond to comments' provides a clear, actionable context for when the tool applies. It does not explicitly name when-not-to-use scenarios or alternatives, but since it is the only reaction-list tool among siblings and the read/write counterparts are obvious, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint:true and destructiveHint:false, and the description is consistent. The description adds mild context by specifying what information is returned (description, completion status) and defining what a step is, but it discloses no additional behavioral traits such as permission requirements, rate limits, 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?

The description is two concise sentences. The first sentence states the action and return content; the second clarifies the domain concept of a step. No filler, redundancy, or irrelevant detail.

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

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

For a simple read-only tool with three fully documented parameters and read-only annotations, the description provides the essential return content ('description and completion status') and domain context. It does not explain how step_id is obtained, but the schema already covers that, so nothing material is missing for a capable 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?

Schema description coverage is 100%, and each parameter is thoroughly documented with examples and an explicit distinction between card_number and card_id. The description itself contributes no parameter-level meaning, 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?

The description states a specific verb and resource: 'Get detailed information about a specific to-do step on a card' and names the key fields returned (description, completion status). It clearly distinguishes this from sibling step operations like create_step, update_step, and delete_step by focusing on retrieval of a single step.

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

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

The description implies a read-only retrieval use case but does not explicitly state when to use this tool versus alternatives such as get_card or list-style tools. It also does not mention that fetching a step might precede an update or delete. The schema parameters provide indirect guidance (step IDs returned when creating steps or fetching card details), but the description itself lacks explicit usage 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?

Beyond the readOnlyHint and destructiveHint annotations, the description reveals a meaningful behavioral guarantee: every upstream page is fetched server-side, so the result is complete and there is no page parameter. It also discloses the returned fields (tag IDs, titles, usage counts), which is especially valuable because there is no output 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?

The description is compact and front-loaded with the main action. The tag-definition sentence adds useful context, and the no-pagination note prevents a wasted call. Minor redundancy exists between 'Get all tags' and 'The result is the complete list,' but it is not harmful.

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 tool with no output schema, the description sufficiently covers what the call returns, the scope of the result, and the absence of pagination. An agent has enough context to invoke it correctly and interpret the response.

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 account_slug parameter is fully documented in the schema, including example formats and how to find available slugs. The description itself adds little parameter-level detail, but the baseline of 3 applies because the schema carries the burden.

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

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

The first sentence states a specific verb and resource: 'Get all tags used in an account.' It also answers the scope question—account-level, not board- or card-level—and no sibling tool offers the same resource, so there is no 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?

The description clearly establishes the tool as the way to retrieve the full tag list for an account, and the complete-list guarantee helps an agent know this is not a paginated endpoint. It does not name alternatives, but none of the sibling tools provide a comparable tag-list operation, so no exclusion is necessary.

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 destructiveHint=false, and the description adds useful behavioral context by enumerating the response content (name, email, role, permissions). Since there is no output schema, this return-shape disclosure carries real value 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, front-loaded sentence conveys the core operation and expected data without filler. Nothing in the description is redundant.

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

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

For a simple read-only fetch by ID, the description plus fully documented schema parameters are largely sufficient. It lacks explicit alternatives and error-case behavior, but these are minor for this tool's complexity and annotation-backed safety profile.

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 both user_id and account_slug already documented in the input schema. The tool description itself adds no parameter-level meaning, so the high-coverage 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?

The description uses a clear verb-resource pair ('Get detailed information about a specific user') and distinguishes this from the plural sibling fizzy_get_users by focusing on a single user. The expected fields (name, email, role, permissions) make 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?

The phrasing 'specific user' implies this tool is for fetching a single user's details versus listing users, but it never explicitly states when to prefer it over alternatives or when not to use it. There is no named sibling or exclusion condition.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: every upstream page is fetched server-side, the result is the complete roster, and there is no further pagination to request. This is exactly the kind of hidden behavior an agent needs to know before invoking.

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: the first defines the operation and output, the second gives the primary use case, and the third resolves the pagination question. The most decision-relevant facts are front-loaded, and there is no redundant restating of the tool name or schema fields.

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

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

For a simple one-parameter, read-only list tool with no output schema, this description is complete. It states what is returned, that only active users are included, that the result is exhaustive, and that no further paging is needed. The account_slug parameter is fully covered by the schema, and the annotations handle the mutation/safety context.

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 account_slug parameter is already well documented in the schema, including an example and cross-references to fizzy_get_identity and fizzy_get_accounts. The description does not add additional parameter-level meaning, but it does not need to because the schema fully carries that burden. 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 uses a specific verb and resource: 'Get all active users in an account,' followed by the concrete return fields (IDs, names, emails, access levels). It also clarifies scope via 'complete roster' and 'no page parameter,' which distinguishes it from any paginated or single-user endpoint like fizzy_get_user. The purpose is immediately 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 explicitly states when to use the tool: 'Use this to discover available users for card assignments.' This gives clear situational context. It does not explicitly name an alternative for retrieving a single user or state when not to use this tool, so it falls short of full exclusion 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 indicate this is a non-read-only, non-destructive mutation, and the description adds meaningful behavioral context: golden cards are highlighted and become filterable via indexed_by='golden'. This goes beyond the structured annotations by describing the persistent effect of the action. It doesn't mention idempotency or the reverse operation, but the core behavior is transparent.

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

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

The description is two sentences with no wasted words. The core action is first, followed by the useful consequence and a concrete usage recommendation. Every sentence earns its place.

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

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

For a simple two-parameter mutation with robust schema descriptions and non-destructive annotations, the description covers what the tool does, why it matters, and how it interacts with another tool. It lacks only minor details such as behavior when a card is already gilded, but nothing critical is missing for correct invocation.

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

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

The input schema already provides 100% coverage with detailed descriptions for both account_slug and card_number, including the distinction between card_number and card_id. The tool description adds no parameter-level meaning beyond that, so the baseline score 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?

The description uses a specific verb and resource: 'Mark a card as golden (priority/important).' It clearly explains what the operation does, differentiates the card's golden state from normal cards, and connects it to the filtering capability in fizzy_get_cards. This is unambiguous and distinct from the sibling tools.

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

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

The description gives clear usage context: 'Use this to flag high-priority work items.' It explains the practical effect (highlighting and filtering) but does not explicitly state when not to use it or mention the alternative ungild_card. Still, the guidance is sufficient for an agent to understand when this tool is appropriate.

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 a mutating, non-destructive operation. The description adds that the operation is bulk and intended after reviewing updates, but it does not disclose side effects, whether notifications are only marked read and never deleted, or any limits/reversibility information. This is acceptable but not richly transparent.

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, first stating the operative action and second stating the use case. There is no filler, repetition of the name, or unnecessary detail.

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

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

For a one-parameter bulk action with complete schema coverage and annotations, the description covers what the tool does, at what scope, and when to use it. It does not describe the return value, but there is no output schema, and the success behavior is predictable for a notification-read action.

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

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

The schema description has 100% coverage for the single account_slug parameter, including an example and a pointer to fizzy_get_identity/fizzy_get_accounts. The tool description adds no additional parameter-level meaning, so the baseline score 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 states a specific verb and resource: 'Mark all notifications in an account as read at once.' This clearly distinguishes the bulk operation from the sibling single-notification tool by making 'all' and 'at once' explicit. It does not explicitly name the alternative sibling, but the scope 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?

It gives a clear when-to-use instruction: 'Use this to clear your notification inbox after reviewing all updates.' It does not explicitly list exclusions or point to mark_notification_read for handling individual notifications, but the context is specific enough for an agent to select this tool.

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

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

Annotations already communicate that the tool is not read-only and not destructive; the description adds the concrete state transition from unread to read. It does not go further to discuss permissions, no-op behavior if already read, or reversibility via the unread sibling, but for a simple mutation this is acceptable.

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 the second sentence adds a legitimate use case. There is no filler or repetition beyond what 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 two-parameter mutation with fully documented schema and annotations indicating it is non-destructive, the description provides enough context for an agent to select and invoke the tool correctly. No output schema or nested complexity creates additional disclosure requirements.

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

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

Schema description coverage is 100%: both account_slug and notification_id are already described with formats and sourcing instructions. The description adds no parameter-level information, 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?

States a specific action ('Mark'), a specific resource ('a specific notification'), and the resulting state ('as read'), with the added clarification that this acknowledges and clears unread status. This distinguishes it from bulk siblings like fizzy_mark_all_notifications_read and the inverse fizzy_mark_notification_unread.

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

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

Explicitly says to use it to acknowledge notifications and clear them from unread status, giving a clear use case. It does not name alternative tools for the inverse or bulk operations, though 'specific notification' implicitly rules out the bulk sibling.

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 readOnlyHint=false and destructiveHint=false, and the description accurately reflects a non-destructive state change. It adds the intention 'flag notifications for later attention', but does not disclose further behavioral details such as idempotency, permissions, or return behavior. No contradiction exists.

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

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

Two short sentences with no filler. The operation is front-loaded, and the purpose follows immediately. Every word adds value.

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

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

For a simple tool with two fully documented parameters and no output schema, the description provides sufficient context about what the tool does and why to use it. It could be slightly stronger by explicitly differentiating from the read-marking sibling, but this is not critical for correct invocation.

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

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

Schema description coverage is 100%, with both account_slug and notification_id clearly documented including format and where to obtain them. The description does not repeat parameter details, which is appropriate since the schema already carries the semantic weight.

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

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

The description clearly states the operation ('Mark ... as unread') and the resource ('a specific notification'). The word 'specific' distinguishes it from bulk notification operations like mark-all, and the unread state distinguishes it from the read-marking 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?

The second sentence gives a clear use case: 'Use this to flag notifications for later attention.' However, it does not explicitly name alternatives or describe when not to use it, such as pointing to fizzy_mark_notification_read for marking notifications as read.

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

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

The description states the core behavior—moving a card—and adds the constraint that the card is moved "from triage." Annotations already indicate this is a non-read-only, non-destructive operation, so the description does not need to repeat that. However, it does not disclose potential side effects, such as whether the card is removed from its previous column automatically, or whether any notifications are triggered. This is a clear but not deeply transparent description.

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 main action and followed by a general usage statement. There is no filler or redundant repetition of the tool name, though the second sentence adds only modest value beyond the first.

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

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

The description is adequate for a simple move operation, and the schema supplies all required parameter context. However, because there is no output schema and no mention of return behavior or error conditions, the description leaves some ambiguity about what happens after a successful move. It is not incomplete enough to fail, but it could be richer.

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 every parameter is already explained in the input schema. The description adds no additional parameter-level detail beyond the tool's overall purpose. Baseline 3 is appropriate because the schema does the heavy lifting and the description does not interfere.

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

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

The description uses a specific verb and resource: "Move a card from triage to a specific workflow column." It clearly conveys the action and the target, and the phrase "from triage" helps distinguish this from other card-moving tools like fizzy_send_card_to_triage and fizzy_move_card_to_not_now, though it does not 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?

The description gives a general usage context: "Use this to transition cards through your workflow stages." It implies when to use the tool, but it does not explicitly distinguish it from sibling move tools or state when not to use it. The schema's column_id description points to fizzy_get_columns, which helps, but the tool description itself lacks explicit 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?

The description adds behavioral context beyond the annotations by stating that the operation 'removes the card from workflow columns but keeps it accessible.' This clarifies that the tool mutates card placement without deleting the card. It does not discuss reversibility or permissions, but for this simple mutation the key behavioral trait 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?

The description is two concise sentences with no redundant wording. The primary action is front-loaded, and the behavioral consequence follows directly. Every sentence contributes useful 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 card-movement tool with fully documented parameters and no output schema, the description covers the essential context: destination, meaning, and effect on the card's location. It is slightly incomplete in that it does not clarify how the card can be restored or whether it remains visible in any default view, but these are minor gaps.

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

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

Schema description coverage is 100%, and both parameters already have detailed descriptions in the input schema, including the distinction between card_number and card_id and how to obtain account_slug. The tool description itself adds no parameter-level meaning, so the baseline score 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 clearly states a specific action ('Move a card to the 'Not Now' triage area') and explains the practical effect (removing from workflow columns while keeping it accessible). It is not a tautology and gives a concrete destination and outcome. It does not explicitly contrast with the similar sibling fizzy_send_card_to_triage, so it falls just short of a 5.

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

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

The phrase 'indicating it's not a current priority' gives an implied usage context, and the sibling list contains many card-movement tools. However, the description does not provide explicit guidance on when to prefer this tool over alternatives like fizzy_move_card_to_column or fizzy_send_card_to_triage, nor does it mention when not to use 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 only provide readOnlyHint=false and destructiveHint=false; the description adds meaningful behavioral scope: pins are per-user and per-account, affecting only the authenticated user's list. It does not mention idempotency or error cases, but for a simple non-destructive mutation this is strong 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?

Four tight sentences, each carrying unique information: action and scope, per-user effect, use case, retrieval path, and a clear alternative. There is no filler or redundancy.

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

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

For a simple two-parameter mutation, the description covers purpose, scope, use case, retrieval route, and the main sibling alternative. The schema fully documents the parameters, and although there is no output schema, the instruction to retrieve results via fizzy_get_pins compensates by telling the agent how to observe the outcome.

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 input schema already documents card_number as the visible board ID distinct from card_id, and account_slug with examples and source endpoints. The description reinforces account independence but does not add parameter meaning beyond what the schema provides.

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

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

The description identifies a specific action (pin a card) with a precise scope: the current user's personal quick-access list. It also distinguishes itself from fizzy_gild_card by contrasting per-user pinning with team-wide flagging, making the purpose immediately clear.

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

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

It explicitly states when to use this tool: to keep track of a card you need to return to. It names the alternative for team-wide priority (fizzy_gild_card) and explains the per-user vs. team distinction, giving clear routing guidance.

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

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

Annotations already indicate this is not read-only and not classified as destructive. The description adds a meaningful behavioral detail beyond annotations: it requires the caller to be the user who originally added the reaction. This is a valuable authorization constraint not present in 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?

The description is only two sentences: the first states the action, and the second adds a critical permission constraint. Both sentences are useful and there is no redundancy or 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 straightforward removal mutation with four well-documented required parameters and no output schema, the description covers the purpose and a key behavioral precondition. It could mention failure cases or response behavior, but the essential context for a correct call is present.

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

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

Schema description coverage is 100%, so all four required parameters are already documented in the input schema. The description adds no additional parameter-level semantics, so the baseline score 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?

The description clearly states the action: remove an emoji reaction from a comment, using a specific verb and resource. It is implicitly distinct from sibling tools like add_reaction and get_reactions, but it does not explicitly name or contrast 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?

It provides a clear precondition: only the user who added the reaction can remove it, which is useful context and an implicit exclusion. However, it does not explicitly guide the agent toward alternatives like fizzy_get_reactions for discovering reaction IDs or fizzy_add_reaction for adding reactions.

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 this is a write operation that is not destructive, and the description adds that the card becomes 'active again' and that closures are undone. This is useful but does not go much beyond the obvious semantic meaning of 'reopen'; it does not mention prerequisites, permissions, or behavior if the card is already active. A 3 is appropriate given the annotation coverage.

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

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

The description is two short sentences with no filler. The core state change is front-loaded, and the use cases are stated immediately after. Every sentence contributes meaning, making this an efficient and well-structured 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?

For a simple two-parameter state-change tool with no output schema, the description plus annotations cover the core purpose, the precondition ('previously closed'), and the intended use cases. There is no critical missing information for an agent to call it correctly, though a note about what happens if the card is already open would be a minor addition.

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

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

The input schema fully describes both required parameters, including the important distinction between card_number and card_id and how to obtain account_slug. Since schema description coverage is 100%, the description does not need to add parameter details, and 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?

The description uses a specific verb ('Reopen') and resource ('previously closed card') and clearly states the result ('make it active again'). It distinguishes this tool from the sibling fizzy_close_card and leaves no ambiguity about the state transition it performs.

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

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

The description explicitly says when to use it: 'resume work on completed cards or undo accidental closures.' This gives clear context and implies the tool is only for previously closed cards. It does not explicitly mention exclusions or compare it with sibling tools like fizzy_update_card, but the usage guidance is strong enough for an agent to select it appropriately.

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 this is not read-only and not destructive. The description adds behavioral context by stating the card is removed from its current column, which clarifies that this is a move operation. It doesn't contradict annotations, and for a simple move operation this is adequate, though richer detail about permissions or side effects is absent.

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

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

The description is two sentences long, front-loads the core behavior, and then gives the intended use case. Every sentence adds value, and there is no redundant or filler content.

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

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

For a two-parameter mutation tool with full schema coverage and annotations covering the mutation profile, the description is largely complete. It explains what happens, why to use it, and when. The main gap is the absence of explicit guidance on how this differs from fizzy_move_card_to_column, but the use-case phrase 'reassess or reprioritize' compensates for most of that ambiguity.

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

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

Schema description coverage is 100%, so the parameters card_number and account_slug are already fully documented. The description does not add parameter-level detail beyond what the schema provides, but no compensation is needed because the schema 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?

The description uses a specific verb and resource: 'Send a card back to the triage area' and explains the mechanism ('by removing it from its current column'). It clearly conveys that this is a move/relocation operation, not a delete or close. It doesn't explicitly distinguish itself from siblings like fizzy_move_card_to_column, but the triage-specific framing makes the purpose clear.

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

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

The description gives explicit intended usage: 'Use this to reassess or reprioritize cards that need more planning.' This gives an agent a clear condition for selecting this tool. However, it does not mention when not to use it or how it differs from alternatives such as fizzy_move_card_to_column.

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

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

The description goes beyond the annotations by disclosing the toggle behavior: if the user is already assigned they will be unassigned, and if not assigned they will be assigned. This is useful behavioral context that the readOnlyHint/destructiveHint annotations alone do not provide.

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

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

Two sentences, front-loaded with the core action and toggle rule, followed by a brief usage statement. There is no redundant restatement of the tool name and every sentence contributes 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 simple toggle endpoint with rich schema descriptions and annotations, the description is complete: it explains the operation, the state-flipping behavior, and the intended use case. It does not describe response payloads or error conditions, but there is no output schema and this could be inferred from typical API behavior.

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

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

Schema description coverage is 100%, and the schema already explains assignee_id, card_number, and account_slug, including examples and the distinction between card_number and card_id. The description adds little to parameter semantics beyond confirming that assignee_id refers to a user and card_number to a card.

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: 'Assign or unassign a user to/from a card.' It also explains the toggle behavior and frames the tool as managing card ownership and responsibilities, which clearly distinguishes it from the tag toggling, watching, pinning, and comment tools among the siblings.

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

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

The description gives explicit context for when to use it: 'Use this to manage card ownership and responsibilities.' It does not list exclusions or direct alternatives, but there is no obvious sibling that performs card assignment, and the toggle semantics and use case are clearly conveyed.

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 indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral details: tags are auto-created if missing, and leading '#' characters are stripped from tag titles. This goes beyond the structured annotations and helps the agent predict side effects beyond the simple toggle 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 short and front-loaded with the core action. The sentence 'Tags help organize and categorize cards' is mild filler but not harmful, and the operationally important details about auto-creation and '#' stripping are included efficiently.

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

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

For a simple three-parameter mutation tool, the description combined with the 100% schema coverage and annotations is sufficient to invoke it correctly. No output schema exists, so return value disclosure is not required. The description explains the main behavioral edge cases (auto-creation and '#' stripping), leaving little ambiguity.

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 each parameter already documented in the input schema. The tool description repeats some of this information (e.g., auto-creation and '#' stripping) but does not add meaning beyond what the schema provides. Therefore the baseline 3 is appropriate.

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

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

The description clearly states the verb-resource pair: 'Add or remove a tag from a card.' It also distinguishes this tool from sibling tools like fizzy_get_tags by focusing on mutating a card's tags rather than listing account-level tags. The auto-creation and '#' stripping details further pin down the exact scope.

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 does not explicitly say when to use this tool versus alternatives, nor does it mention exclusions or related tools. The use case is implied by the tool name and purpose, but there is no guidance such as 'use fizzy_get_tags to list existing tags' or 'for assignment, use fizzy_toggle_card_assignment.'

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

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

The description goes beyond the annotations by explaining the observable consequences: the card will no longer appear in golden card filters and will lose priority highlighting. Since readOnlyHint=false and destructiveHint=false already signal a non-read-only but non-destructive operation, the description usefully clarifies the exact state change. It does not cover edge cases like applying it to an already-ungilded card, but it provides meaningful behavioral 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 two short sentences with no filler. The primary action is front-loaded, and the effects are stated immediately. Every sentence earns its place.

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

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

For a simple, focused status-removal operation, the description covers the purpose and the observable effects. It does not specify what the response looks like, but no output schema exists and the state change is described well enough for an agent to understand the outcome. Minor missing details, such as reversibility, prevent a perfect score.

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

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

Schema description coverage is 100%, and both parameters are already well-documented with examples and guidance. The description itself adds no additional parameter-level detail. This matches the baseline of 3 for cases where 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?

The description uses a specific verb and resource: 'Remove golden status from a card.' It clearly identifies the operation and differentiates it from sibling tools like fizzy_gild_card and other card mutations. There is no ambiguity about what the tool does.

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

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

The description clearly implies the use case: reversing or removing a card's golden status. However, it does not explicitly name fizzy_gild_card as the inverse operation or state conditions for when not to use it. The intended context is clear, but exclusions and alternatives are left implicit.

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

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

Annotations already declare this as a non-read-only, non-destructive operation. The description adds value beyond annotations by specifying exactly what state mutates (the user's pin list) and what remains untouched (the card and its board position), giving the agent a clear blast-radius picture. It doesn't cover idempotency or failure behavior, but the annotations lower the bar and the added scope detail is genuinely useful.

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 core action and outcome are front-loaded in the first sentence, and the second sentence adds the critical scope boundary. 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 simple two-parameter tool with no nested objects and no output schema, the description plus rich schema documentation is nearly complete. The only minor gaps are idempotency (what happens if the card isn't pinned) and an explicit pointer to the inverse operation, neither of which is essential for correct invocation.

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

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

The tool description adds no parameter information, but the schema description coverage is 100% — card_number is explained as distinct from card_id, and account_slug includes lookup guidance via fizzy_get_identity or fizzy_get_accounts. With the schema already carrying the full burden, baseline 3 is appropriate.

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

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

The description states a specific verb (unpin) and resource (card) with a precise outcome: removing it from the user's personal quick-access list. It also explicitly distinguishes this from card-level mutations by clarifying the card itself is unchanged, which differentiates it from siblings like fizzy_delete_card and fizzy_close_card.

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 provides clear scope context: this affects only the authenticated user's pins and not the card itself, which implicitly tells the agent this is not the tool for board or card modification. However, it does not explicitly name alternatives (e.g., fizzy_unwatch_card for watch removal, or fizzy_pin_card as its inverse) or state exclusion conditions, so it falls short of a full 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 declare readOnlyHint=false and destructiveHint=false, covering the safety profile. The description adds the behavioral consequence ('You'll stop receiving updates about card changes'), which aligns with the annotations. It does not disclose reversibility or whether existing notifications remain, but the annotation bar is already met.

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: action, effect, and use case. The core verb is front-loaded and there is zero wasted wording.

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

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

For a simple two-parameter state mutation with full schema coverage and annotations present, the description is nearly complete. Minor omissions like reversibility (re-watching) and effect on already-existing notifications do not block correct invocation.

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

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

Schema description coverage is 100% with detailed parameter docs: card_number distinguishes itself from card_id and account_slug explains format and how to discover values. The tool description adds no paramater info, but the schema already carries the full burden, so baseline 3 applies.

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

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

The description states a specific verb+resource ('Unsubscribe from notifications for a card') and the practical effect ('stop receiving updates about card changes'). It is clearly distinct from the inverse sibling fizzy_watch_card and from notification-reading tools, though it does not explicitly name any sibling to differentiate itself.

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

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

The description gives actionable usage context: 'Use this to reduce notification noise for cards you're no longer actively involved with.' It does not name alternatives or exclusions (e.g., when to use fizzy_mark_notification_read instead), but the stated condition for use is clear enough.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds that this only modifies board metadata and does not affect cards or columns, which is useful behavioral context beyond the annotations. The unsupported 'other properties' claim slightly clouds the scope but does not contradict the annotations.

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

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

Two sentences with no fluff; the core action is front-loaded and the clarifying scope statement is concise. 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 simple 3-param tool with annotations, the description covers the basic action and scope. However, the misleading 'other properties' leaves ambiguity about what can be updated, and the description does not mention any return value or side effects, so it is not fully 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 baseline is 3, but the description actively misleads by suggesting 'other properties' are updatable when additionalProperties=false and only name is a mutable field. It does not add accurate meaning and instead undermines the schema's clarity.

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

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

The description clearly identifies the verb ('Update') and resource ('existing board'), and distinguishes this tool from siblings by noting it does not affect cards or columns. However, the phrase 'or other properties' is vague and not reflected in the schema, preventing a perfect score.

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

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

The description implies the tool is for an existing board but provides no explicit when-to-use guidance or alternatives. The note about not affecting cards or columns hints at scope but does not name sibling tools or state when to choose this over create/delete or update tools for other entities.

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, the description and schema disclose important behaviors: updates are partial, provided fields replace rather than merge, tags/assignees/descriptions/column are fully replaced, and due_on can be nulled. The assignee note even explains the five-assignee rejection and the read-back check. There is no contradiction with readOnlyHint=false or destructiveHint=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?

The tool description is two short sentences that front-load the action, scope, and the crucial partial-update behavior. It is efficient and contains no filler.

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

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

The definition is largely complete: required parameters are declared, all optional parameters explain omission semantics, and replacement warnings are present. There is no output schema, but the assignee description compensates by describing the read-back behavior. A brief note about the response format would make it fully complete, but it is not essential for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds a general 'only provided fields will be changed' rule, but each property already says 'omit to keep current,' so the description doesn't provide meaning beyond the schema. Per-parameter details like null due_on, empty assignee arrays, and replacement semantics are already 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 clearly states the tool updates an existing card and lists the editable properties, which is more specific than just repeating the name. However, it does not explicitly distinguish itself from sibling tools like fizzy_move_card_to_column or fizzy_toggle_card_tag, so it falls just short of full differentiation.

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

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

The top-level description itself gives no when-to-use guidance, but the input schema property notes explicitly route users to fizzy_close_card and fizzy_reopen_card for archiving workflows, to fizzy_toggle_card_tag for individual tag changes, and to fizzy_toggle_card_assignment for individual assignment changes. This is strong contextual guidance, though it doesn't mention fizzy_move_card_to_column as an alternative for column placement.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds a meaningful behavioral guarantee ('This does not affect cards in the column') beyond the structured metadata. It does not cover permissions or response details, but for a rename/recolor operation this is acceptable.

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 no redundant wording. The action and scope are front-loaded, and each sentence contributes meaningful 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 simple update operation with fully documented parameters and ID-source references in the schema, the description is largely complete. The only minor gap is not stating that at least one of name or color should be supplied, but this is unlikely to block correct invocation.

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