AgileHero

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

Goes well beyond the annotations (which only mark it non-readonly, non-idempotent, non-destructive). It discloses partial-failure semantics with a per-index failed array, stage-gating with the wrong_stage error code, recipient_id being required in new-model kudos and refused on classic boards, note visibility once revealed, and a Pro/trial workspace requirement.

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

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

Front-loaded with the core action and dense with load-bearing detail, but it renders as one long paragraph rather than scannable segments. Nothing is filler, yet the wall-of-text form slightly hurts readability.

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 the return burden itself by explaining the failed array, and it covers preconditions, error codes, limits, and the plan requirement. Nothing an agent needs to call it correctly is missing.

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

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

With only 50% schema description coverage, the description compensates fully: column accepts a case-insensitive title or a uid from get_retrospective, text has the 1000/255 character split, and recipient_id has conditional requirements. This adds real meaning beyond the schema strings.

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

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

States a specific verb and resource ('Add items to a retrospective') and immediately pins the batch scope ('several at once'), plus the two board flavors it serves. An agent can tell it apart from create_card or move_retro_item without opening either schema.

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

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

Gives explicit preconditions and exclusions: notes are accepted only while the retro is open for notes or in the Write stage, otherwise the call is refused with wrong_stage, and it routes the agent to get_retrospective for the column uid. It does not name a sibling alternative, but no direct alternative exists for this operation.

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 provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral details: 'One conversion per node: already-converted nodes are rejected up front — resubmit without them.' This is non-obvious and not covered by annotations. It also clarifies that unlisted nodes are ignored, preventing partial conversion surprises. No contradiction with annotations; the description enriches the behavioral profile.

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

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

The description is dense but well-structured: it starts with the main purpose, then details the role mapping, and ends with constraints and prerequisites. Each sentence adds value; there is no fluff. It is somewhat long, but given the complexity of the per-node mapping, the length is justified and front-loaded with the core concept.

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 covers the input requirements, role semantics, constraints (max 200 nodes, one conversion per node), and prerequisites (Pro workspace). It does not explicitly describe the return value, but for a conversion tool, the primary need is to understand the mapping logic. Given the absence of an output schema, a brief note on the response would strengthen completeness, but the description is sufficient for an agent to invoke the tool correctly.

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

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

The schema covers all three parameters with descriptions, but the tool description adds essential semantics for the 'nodes' array by explaining each role ('epic', 'existing_epic', 'card', 'label', 'skip') and the hierarchical label behavior. It also clarifies the special requirement of target_epic_id with role 'existing_epic'. This goes beyond the schema's terse descriptions, providing the agent with the mapping logic needed to populate parameters correctly.

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's purpose: 'Convert a mind map into backlog items with a per-node mapping.' It specifies the resource (mind map) and the action (convert), and distinguishes itself from siblings like convert_whiteboard_element by being specific to mind maps and the per-node role mapping. The explanation of roles (epic, existing_epic, card, label, skip) is concrete and 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 gives explicit usage instructions: pass the ROOT element uid as id and list nodes to convert, with unlisted nodes ignored. It also states a prerequisite: 'Requires a Pro or trial workspace.' It does not explicitly mention when not to use this tool versus alternatives like create_card, but the context is clear that this is for bulk conversion from mind maps. The guidance is specific and actionable.

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) are consistent with the description, which discloses detailed behavior: conversion types, child re-assignment, element stays on board, link via get_whiteboard, one-time conversion, title defaulting, and workspace requirement. This goes well beyond annotations and provides rich context for the agent.

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

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

Three sentences, front-loaded with the core purpose, then behavior and constraints. No fluff, every sentence adds value. Well-organized for an agent to parse.

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

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

Given the tool's complexity (5 params, conversion rules, constraints), the description covers all essential operational details: what can be converted, how children are handled, link visibility, one-time conversion, default title, and workspace requirement. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with all five parameters described. The description adds some behavioral context (e.g., title defaults, conversion rules) but doesn't add per-parameter semantics beyond what the schema already provides. It's a baseline 3 because 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?

Description states a specific verb (Convert) and resource (whiteboard element into backlog item), and differentiates types (sticky note to card/epic, frame to epic). It clearly distinguishes from sibling tools like create_card/create_epic (which create new items from scratch) and convert_mind_map (different source). The purpose 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?

Clear context for when to use: when you have an existing whiteboard element to turn into a backlog item. It mentions constraints like 'only converted once' and the Pro/trial workspace prerequisite. However, it doesn't explicitly name alternatives or say 'when not to use' – but the purpose clarity effectively differentiates it.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds valuable behavioral context: labels not existing are created on the project (side effect), description must be in AgileHero Markup (format constraint), estimation is Fibonacci complexity not time, and epics/assignees must already exist (prerequisites). No contradictions with annotations; this enriches the agent's understanding.

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 essential purpose and required parameters, then systematically covers optional behaviors and constraints. Every sentence adds unique value—there is no fluff or repetition of schema details. It is longer than average but each clause earns its place, making it dense yet efficient.

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

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

Given the tool's complexity (15 parameters, nested objects for checklists/attachments/relations, and multiple enums), the description covers the critical aspects: required fields, default behaviors (backlog, end of queue), format requirements (AHM), prerequisites, side effects (label creation), and the ability to supply related items in one call. There is no output schema, so return details are not required. The description is comprehensive for an agent to call this correctly.

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

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

Schema description coverage is 80%, but the description adds significant meaning beyond the schema: it clarifies that only project_id and title are required, explains the effect of omitting list_id and position, defines estimation as Fibonacci not time, notes that labels are auto-created, and points to list_epics and list_project_users for validation. This goes well beyond a simple mapping of parameter names.

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's action: 'Create a card on a project's kanban board.' It specifies the resource (card) and the context (project's kanban board), and differentiates from siblings like update_card, move_card, and delete_card by focusing on creation. The statement 'Only project_id and title are required' further clarifies the core 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 provides explicit usage guidance: omitting list_id places the card in the backlog, omitting position joins the end of the queue, and references move_card for the position contract. It also instructs to read get_ahm_spec before using description, and clarifies prerequisites for epic_id and assigned_to via list_epics and list_project_users. This goes beyond vague when-to-use and offers actionable conditions.

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

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

The description discloses several non-obvious behaviors beyond the annotations: attribution to the signed-in user, persistence in later get_card/get_epic responses, lack of edit support, normalization of nested replies to the thread root, and rejection of cross-resource parent uids. This is exactly the kind of context an agent needs.

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

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

The description is dense but every sentence earns its place. It is front-loaded with the core purpose and then systematically adds constraints, alternatives, and edge cases. There is no filler or repetition of schema details.

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

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

Given four parameters, a required mutual-exclusion rule, thread semantics, content-format restrictions, and no output schema, the description covers the full complexity of the tool. It even explains how the result is observable (subsequent get_card/get_epic responses) and states an explicit rejection condition for invalid parent uids.

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 the schema already covers all four parameters, the description adds meaning beyond it: mandatory mutual exclusivity of card_id and epic_id, the exact AHM comment-surface restrictions, the 'read get_ahm_spec first' requirement, and the validation behavior for invalid parent_comment_id values. This meaningfully exceeds the schema baseline.

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

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

The description opens with a specific verb and resource: 'Add a comment to a card or to an epic.' This immediately distinguishes it from sibling create_* tools (create_card, create_epic, create_wiki_page) and from its complement delete_comment. The scope is unmistakable.

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 instructions: provide exactly one of card_id or epic_id, read get_ahm_spec first, never use markdown/HTML, and use delete_comment for corrections since comments cannot be edited. It also clarifies thread behavior and rejection rules, leaving little to inference.

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

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

Annotations only state readOnly=false, idempotent=false, and destructive=false, so the description carries the behavioral burden. It discloses the returned new epic uid, how other tools consume that uid, and that multiple sub-resources can be created in the same call. The mutation effect is clear from 'Create', though explicit side-effect notes are 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?

Four tightly written sentences with zero filler: required fields and the markup constraint are front-loaded, while cross-tool return semantics are delivered at the end. 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 10-parameter write tool with no output schema, the description covers required fields, the AHM prerequisite, assignee discovery, bundleable resources, and the UID return value. Optional fields like color and dates are self-explanatory from the schema; explicit error/permission notes would be the only notable gap.

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

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

Schema coverage is 90%, so the baseline is 3. The description mostly restates schema facts such as required fields, AHM formatting, and list_project_users for assignees. It adds cross-tool uid semantics but little new per-parameter meaning beyond what the schema already documents.

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

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

The description opens with a concrete verb+resource: 'Create an epic on a project,' and immediately clarifies that only project_id and name are required. It does not explicitly contrast with sibling create/update tools, though mentioning that the returned uid is consumed by create_card/update_card and create_roadmap_slot gives useful role 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?

It gives actionable invocation context: read get_ahm_spec before writing description, source assignee uids via list_project_users, and optionally bundle checklists/links/attachments in the same call. It stops short of explicit 'use X instead' or when-not conditions, so it earns a 4 rather than 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 include idempotentHint=true, but the description expands on this by detailing the case-insensitive match and that the existing label is returned unchanged. It also discloses that the new label is appended to the end of the display order. This adds meaningful behavioral context beyond the annotations, though it does not cover error scenarios or permissions.

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

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

Two sentences with no extraneous information. The primary purpose is stated first, followed by important idempotency and ordering details. The structure is efficient and front-loaded.

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

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

For a simple two-parameter create tool with annotations covering idempotency, the description provides sufficient context: what it does, the duplicate behavior, and ordering. It does not explicitly state the return value, but it is implied (the label or existing label). Given the simplicity, this is adequately 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 description coverage is 50% (project_id has a description, name does not). The description does not add any parameter-specific details; 'by name' merely restates the parameter's existence. It fails to compensate for the missing description of name (e.g., constraints, format, case sensitivity), leaving the agent without clear parameter semantics.

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

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

States a specific verb and resource: 'Create a new label on a project by name.' The idempotency behavior is clearly described, and the tool is distinguishable from list_labels (which reads) and other create tools by its focus on label creation.

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?

Implied usage is to create a label, and the idempotency hint suggests it can be used safely without checking existence first. However, no explicit guidance is given about when to prefer this over alternatives like list_labels, and no exclusions or preconditions are stated.

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

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

Beyond the annotations (mutating, non-idempotent, non-destructive), the description adds meaningful behavior: a new-model retro comes from a template, is open for notes immediately, and makes the caller facilitator, while classic boards only accept name/date/previous_retrospective_id and reject the rest. It notes defaults and that the caller is always a participant. It does not discuss failure modes beyond argument refusal or any rate/permission nuances.

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?

It is front-loaded with the core purpose, but the body is dense, run-on and largely unstructured, packing mode differences, defaults and constraints into fewer, longer sentences. Every clause carries some information, but readability suffers and it could be trimmed and organized better.

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 complex 12-parameter, two-mode tool with no output schema, the description covers both creation paths, key defaults, the required workspace plan, and even the response shape (as get_retrospective returns it). Enough for an agent to invoke it correctly, though it leans on the agent to infer some mode-specific field applicability.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: participant_ids omitted means every project member with write access, the caller is always included, anonymity defaults to the template's value, and classic boards only take a subset of fields. These clarifications exceed what the field descriptions alone convey.

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

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

States a specific verb and resource ("Create a retrospective") and immediately differentiates the two modes it can produce: new-model where the workspace supports them, classic otherwise. It also names sibling relationships (get_retrospective's response shape, add_retro_items that can follow), so an agent can place it precisely among siblings.

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

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

Gives clear conditional guidance: use the new-model path where the workspace has them, otherwise a classic board, and classic boards refuse the new-model arguments. It also discloses the Pro/trial workspace prerequisite. It stops short of explicitly naming an alternative tool to call instead in edge cases, but the when/when-not conditions are well covered.

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

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

Annotations only provide negative hints (not read-only, not idempotent, not destructive), so the description carries the behavioral burden. It meaningfully discloses that an epic may hold multiple slots, overlaps are allowed by design, and a Pro or trial workspace is required. This goes beyond the schema and is useful for anticipating 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?

Three concise sentences, with the purpose front-loaded and no fluff. The behavioral caveat and workspace requirement each earn their place without restating schema 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 create tool with no output schema and fully documented parameters, the description covers the important non-schema context: multiple slots, overlap tolerance, the need to check list_roadmap_slots when extending, and the Pro requirement. It does not describe the return value, but that gap is modest given the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds only 'optionally with assignees' and the date-range framing, which is helpful but not a major compensation for missing schema detail. 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 opens with a specific verb and resource: 'Schedule an epic on the project roadmap: a slot from start_date to end_date'. It clearly differentiates this from sibling tools by framing it as adding a slot, and even contrasts it with extending an existing one.

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 usage context ('Schedule an epic on the project roadmap'), a when-not-to-use signal ('check list_roadmap_slots first if you mean to extend an existing slot rather than add one'), and a prerequisite (Pro or trial workspace). It doesn't explicitly name update_roadmap_slot as the alternative, but the guidance is otherwise unambiguous.

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, consistent with 'Create'. The description adds the prerequisite of a Pro or trial workspace, which is valuable behavioral context beyond annotations. No contradiction.

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

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

Two concise sentences with no waste. The primary action is front-loaded, followed by a pointer to the next step and the licensing requirement.

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 creation tool with no output schema, the description covers the action, the next step, and a key requirement. It does not describe the response format, but that is not critical for invocation.

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

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

Schema coverage is 100% and both parameters have clear descriptions ('Whiteboard name' and 'The unique identifier of the project'). The description does not add additional parameter detail beyond the schema, so baseline 3 applies.

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

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

Description states 'Create an empty whiteboard on a project' with a specific verb and resource, and explicitly distinguishes from 'create_whiteboard_elements' by saying to add content with that tool. Clearly differentiates from siblings like create_whiteboard_diagram.

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 hint by pointing to 'create_whiteboard_elements' for adding content, and notes the Pro or trial workspace requirement. Does not explicitly state when not to use this tool vs alternatives, but the context 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 only say readOnlyHint=false, destructiveHint=false. Description adds significant behavioral detail: transactional all-or-nothing, layout runs once and never again, returns element uids keyed by node ids, and placement below existing content. This goes far 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?

Dense but every sentence adds value: core purpose, layout behavior, transactional guarantee, limits, shape guidance, edit path, and licensing. No fluff, well front-loaded.

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

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

For a complex tool with nested objects and no output schema, description covers input format, constraints, layout behavior, return value, and alternative. Nothing missing that an agent needs to call correctly.

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

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

Schema coverage is 57%, so description must compensate. It clarifies nodes/edges semantics (no coordinates, local ids), shape meanings (diamond=decision, etc.), and groups behavior. It doesn't cover origin_x/origin_y in detail but implies defaults. Adequately compensates for gaps.

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

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

States a specific verb (draw), resource (whiteboard diagram), and input format (semantic graph). Differentiates from create_whiteboard and create_whiteboard_elements by emphasizing server-side layout and no coordinates. The distinction is 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?

Explicitly says when to use (semantic graph input) and when not (edit via update_whiteboard_elements, split >20 nodes). Also mentions Pro workspace requirement, which is a usage condition. No ambiguity.

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 discloses rich behavioral context beyond the minimal annotations: all-or-nothing transactionality, one realtime event, server-side application of native sizes/colors/text placement, auto-arrangement behavior, and the rule that connector anchors are computed by the UI rather than coordinates. This goes well beyond what the annotations reveal.

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 densely informative with no filler. Each sentence covers a distinct concern: batch semantics, server-side defaults, coordinate handling, frames, connectors, and workspace requirements. Key behavioral points are front-loaded before optional 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?

Given the tool's complexity — 6 top-level params, 15 element types, refs, connectors, arrangement options, and no output schema — the description covers all necessary invocation aspects. It explains atomicity, defaults, ref resolution, layout control, connector rules, and licensing. Nothing essential for correct use 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?

Even though schema coverage is 100%, the description adds meaningful semantics: it explains the effect of omitting x/y, maps arrange/origin_x/origin_y/gap to auto-arrangement, clarifies parent_id vs parent_ref resolution, and explains that connectors bind by uid/ref and never coordinates. This materially helps an agent choose and fill parameters.

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: "Create up to 100 whiteboard elements in one transactional call" — this clearly identifies what the tool does and its batch/atomic nature. It distinguishes itself from sibling tools like create_whiteboard and update_whiteboard_elements by focusing on elements and batch semantics.

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 direction: omit x/y for auto-arrangement, provide x/y for full control, and explains when to use refs vs IDs for frames and connectors. It also states a prerequisite (Pro or trial workspace). It does not explicitly name alternative tools for non-batch or single-element cases, so it stops just short of full when-to-use/when-not-to-use 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?

Beyond the basic annotations, the description discloses important behaviors: content format enforcement, rejection of markdown/HTML, return fields (uid, url, document_version, content), and the workspace entitlement. This is meaningful behavioral context, especially since the annotations are sparse and non-destructive hints are 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?

Three compact sentences front-load the core purpose, then add the most critical usage constraint, return values, and entitlement requirement. Every sentence contributes necessary information without redundancy or fluff.

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

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

For a create tool with no output schema and moderate complexity, the description covers prerequisites, content format, rejection behavior, return payload, and licensing. Combined with a fully documented input schema, an agent has enough context to invoke the tool correctly.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds real value by explaining the required AHM wrapper, rejection of non-AHM formats, and pointing to get_ahm_spec for content requirements, which clarifies the content parameter beyond its schema description.

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

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

The description names the specific action (create), resource (wiki page), and the key constraint (AHM content, optionally in a folder). It clearly distinguishes this from siblings like update_wiki_page and show_wiki_page, making the tool's 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 description gives clear context: content must be AHM, not markdown/HTML, and the agent is told to read get_ahm_spec first. It also notes the Pro/trial workspace requirement. It does not explicitly state when to avoid this tool, but the creation-focused purpose and explicit prerequisites provide strong 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 mark destructiveHint and idempotentHint, but the description adds crucial context: soft-delete semantics, the exact side effects on related data, that the epic is preserved, and that undelete is unavailable. This goes well beyond the annotations and fully discloses the tool's 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?

A single, information-dense sentence that front-loads the action and then enumerates effects in a logical order. No filler – every clause conveys a distinct behavioral fact.

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 delete tool with one parameter, this description covers all necessary behavioral context: the operation type, side effects, irreversibility, and what is not deleted. No output schema is needed for a delete; the agent knows what to expect. It is fully sufficient.

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% – the only parameter 'id' is described as 'Card uid'. The description merely refers to 'by its uid', adding no new constraints or format details. With full schema coverage, a 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 action ('Soft-delete a card by its uid') and enumerates concrete side effects: leaving board/listings, removing relations, deactivating estimation sessions, unlinking whiteboard elements, and clarifying the epic is not deleted. This clearly distinguishes it from sibling delete tools like delete_epic or 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?

It does not explicitly name alternatives, but the warning 'There is no undelete through MCP' implicitly tells the agent to be cautious. The resource type (card) is unambiguous among siblings, making the intended use clear, though it could have explicitly stated when to prefer this over update_card or other delete 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?

Beyond the destructive and idempotent annotations, the description discloses the tombstone behavior for replies, the client/session attribution model, and the irrelevance of other users' comments. These behavioral details materially change what an agent should expect after the call.

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

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

Three dense sentences, each carrying distinct information: ownership constraint, correction workflow, and post-deletion behavior. The most important scoping information is front-loaded.

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

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

For a single-parameter mutation with rich annotations, the description fully covers ownership, source of the uid, correction pattern, and outcome for replied-to comments. No critical detail needed for correct invocation is missing.

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

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

The schema already fully documents the single 'id' parameter as a comment uid, so the baseline is 3. The description adds value by explaining where those uids come from, which is not present in the schema.

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

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

The description uses a specific verb and resource ('Delete a comment') and immediately restricts scope to comments posted by the signed-in user, distinguishing it from other delete tools and from comment creation. It clearly identifies the object type and the ownership constraint.

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 that only the signed-in user's own comments may be deleted, explains the correction pattern using create_comment, and directs the agent to get_card / get_epic for comment uids. This gives clear when-to-use and when-not-to-use 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 provide destructiveHint and idempotentHint, and the description adds substantial behavioral detail beyond them: it is a soft delete, cards are preserved and detached, roadmap slots are permanently removed because a slot is meaningless without an epic, and whiteboard elements are unlinked. This is exactly the side-effect disclosure needed for safe tool invocation. 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 operation and then organizes side effects in clean, separate clauses. The parenthetical explaining why roadmap slots are deleted adds rationale without bloat. Every sentence earns its place and there is no filler.

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

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

For a one-parameter, no-output-schema deletion tool, this description is complete: it states the deletion type, the target, and all significant consequences on related objects. Idempotency is already covered by annotations. An agent can accurately predict the outcome of calling this tool without further documentation.

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 documents 'id' as the Epic uid. The description essentially repeats 'by its uid' without adding format, validation, or contextual detail beyond the schema. Baseline 3 is appropriate because the schema already carries the parameter 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 'Soft-delete an epic by its uid', a specific verb-plus-resource statement that clearly identifies the operation. It distinguishes this tool from siblings like delete_card and delete_roadmap_slot by emphasizing that the epic is soft-deleted while related objects behave differently. This is unambiguous and not a tautology.

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 name alternatives, but it gives clear contextual boundaries: cards are NOT deleted, so an agent wanting card deletion knows this tool will not do it; roadmap slots ARE permanently deleted, which matters when choosing between delete_epic and delete_roadmap_slot. Naming the alternative tools directly would make this a 5.

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

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

The description adds significant behavioral context beyond the destructiveHint annotation: it emphasizes permanence ('no trash'), what gets destroyed (assignee links), and what is preserved (the epic). It also notes the workspace requirement. These details are not inferable from annotations alone.

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

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

The description is compact and front-loaded with the critical warning ('PERMANENTLY delete'). Every sentence adds value: scope, irreversibility, alternative suggestion, and prerequisite. No redundancy or fluff.

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

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

For a single-parameter delete operation, the description is complete. It covers the action, scope, side effects, prerequisites, and alternative. No output schema exists, but none is needed for a deletion that returns no meaningful body. The annotations already cover the destructive nature, and the description fills all other 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?

The only parameter (id) is fully described in the schema as 'The roadmap slot uid (from list_roadmap_slots)', which is 100% coverage. The description adds no extra meaning beyond this, so it meets the baseline for schema-documented parameters.

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: 'PERMANENTLY delete a roadmap slot (and its assignee links).' It uses a specific verb and resource, and immediately distinguishes itself from sibling tools like update_roadmap_slot and delete_epic by noting the epic is not touched and that rescheduling should use the update tool.

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 provides when-not-to-use guidance: 'to reschedule, prefer update_roadmap_slot' and clarifies scope with 'The epic itself is not touched.' It also states a prerequisite (Pro or trial workspace). This leaves no ambiguity about when this tool is appropriate versus alternatives.

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

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

Annotations already declare destructiveHint=true, but the description adds significant behavioral context beyond that: children of frames/mind-maps are released (not deleted), connectors dangle, and the operation is transactional with a 100-element limit. It also mentions workspace requirements. 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?

Three sentences with no waste. The main action and limit are front-loaded, followed by critical behavioral nuances. Every sentence earns its place, and the structure is scannable.

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 delete operation with no output schema, the description covers everything an agent needs: prerequisites, side effects (children release, dangling connectors), limits, and workspace requirements. It is complete and actionable.

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 both parameters described, so the baseline is 3. The description adds value by explaining that ids are element uids from get_whiteboard and clarifying the implications of deleting certain element types (frames/mind-maps). This enriches understanding beyond the schema.

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

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

The description clearly states the action (delete), resource (whiteboard elements), and key constraints (up to 100, transactional). It distinguishes itself from siblings by explaining the specific behaviors of frames/mind-maps and connectors, making it unambiguous which tool to use for bulk whiteboard element deletion.

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 clear context on when to use this tool (deleting multiple whiteboard elements) and notes the prerequisite that uids come from get_whiteboard. It also mentions the Pro/trial workspace requirement. However, it doesn't explicitly state alternatives or when not to use it, though the sibling set makes this 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 indicate read-only, idempotent, and non-destructive. The description adds context that this tool returns a specification, not data, and points to a web URL for the same content, which helps set expectations. It does not contradict 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 one dense paragraph but each sentence adds value: the exclusivity of the format, the action to take, the content covered, and a reference link. It could be slightly more structured but is efficient and front-loaded with critical 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?

Given zero parameters, no output schema, and simple tool nature, the description fully tells an agent what it will get (the specification) and how to use it. Nothing essential is missing.

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

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

The schema has zero parameters, so the description only needs to convey what the tool returns, which it does thoroughly. With no parameters, a high score is justified because the description explains the tool's purpose and output fully.

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 it is the AHM v1.0 specification, the only accepted rich-text format, and lists what it covers (vocabulary, attributes, escaping, example). It clearly distinguishes from siblings by being a reference tool rather than a mutation tool.

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 to read this once before writing or editing rich text, and notes that markdown and HTML are rejected. This gives clear when-to-use guidance and implies when not to use (for non-rich-text operations).

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, idempotentHint=true, and destructiveHint=false, and the description's 'Read one card in full' aligns with those. The description adds meaningful behavioral context by detailing exactly what data is returned and emphasizing that only the uid is required, which goes beyond the annotations without contradicting them.

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

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

The description is dense but efficient, front-loading the core purpose and then listing the exact returned fields. The long enumeration is warranted given there is no output schema, and there is no filler or redundancy. It could be slightly more scannable, but 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?

With no output schema, the description carries the full burden of explaining what the agent will receive, and it does so comprehensively: it lists every card component from AgileHero Markup and description_version through threaded comments. It also covers the only input requirement and the source of valid ids, making the tool fully actionable.

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 fully documents the id parameter with 'The unique identifier of the card'. The description adds value by specifying that this is a card uid, that it is the only needed input, and that valid uids come from list_cards, search, or search_cards — useful provenance not present in the schema.

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

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

The description opens with 'Read one card in full', a precise verb-resource pairing that clearly distinguishes this from list_cards, search_cards, and other get_* siblings. It then enumerates the full payload scope (description, block ids, placement, epic, labels, assignees, etc.), leaving no ambiguity about what the tool returns.

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: it takes a card uid alone, explicitly notes there is no project_id parameter, and tells the agent where card uids come from ('Card uids come from list_cards, search or search_cards'). It stops short of explicitly contrasting with sibling tools or saying when not to use it, so it earns a 4 rather than 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 cover the safety profile (readOnly=true, idempotent=true, non-destructive), so the bar is lower; the description instead adds real behavioral context: the null-list-means-backlog convention, board-order delivery of cards, threaded comments, and the tie-in of description_version as an input for preview_description_update/update_description. It stops short of static pagination or rate-limit notes.

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

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

Front-loaded with the core action, then a single dense enumeration, closing with the input constraint. The result-list parenthetical is long but each clause carries usable information. Slightly heavy, but no filler sentences.

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

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

No output schema exists, so the description bears the full burden of describing return values, and it does so item by item, including edge semantics (null list = backlog) and card ordering. An agent has everything needed to call this correctly 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 coverage is 100% and there is only one parameter, so the baseline is 3. The description still adds value the schema lacks: the id is explicitly the epic uid and there is deliberately no project_id parameter, plus where to obtain the uid.

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

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

States a specific verb and resource ('Read one epic in full') and then enumerates the returned surface: AgileHero Markup description with block ids, description_version, name, number, dates, assignees, checklists, cards and threaded comments. It is clearly distinguishable from siblings like list_epics, get_card and update_epic.

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

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

Gives the selection signal for a sibling ('this is the way to list all cards of an epic and see which are to do, in progress or done') and points to the producers of the required id ('Epic uids come from list_epics or search'). It does not state an explicit when-not-to-use case, but the routing information is concrete.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful context beyond the annotations: it indicates the call is 'Cheap' (a performance characteristic) and 'Requires a Pro or trial workspace' (an access constraint). It does not contradict any annotation, and the added context helps an agent judge whether and under what conditions to invoke it.

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 no filler: the first states what the tool returns, the second explains its relationship to a sibling and gives a usage directive, and the third states the access requirement. The key information is front-loaded, and every sentence earns its place. This is a model of concise tool documentation.

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 tool, the description is complete: it names the returned fields, points to list_attention_cards for the underlying definitions, explains why to call it first, and notes the workspace requirement. The absence of an output schema is acceptable because the description enumerates exactly what the response contains. An agent has all the information needed to decide whether to call this tool and how to invoke it correctly.

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

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

The schema has 100% coverage on the single required parameter project_id, fully describing it as the unique identifier of the project. The description does not add extra parameter-level detail, but with full schema coverage the baseline of 3 is appropriate. The description's mention of the specific output fields partially clarifies what the project_id will be used for, but no additional semantics are strictly needed.

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's purpose: returning counts of cards needing attention on a project's kanban board. It enumerates the exact fields returned (overdue_cards_count, blocking_cards_count, stuck_cards_count) and differentiates from the sibling list_attention_cards by noting that sibling returns the cards behind each count. This gives an agent a precise understanding of what the tool does and how it differs from a nearby alternative.

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

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

The description explicitly says 'call this first to decide whether a deeper look is worth it', which is direct guidance on when to use it. It also contrasts with list_attention_cards ('returns the cards behind each count'), so an agent knows to use that sibling when it needs the actual cards rather than just counts. This is exactly the kind of explicit usage routing expected.

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 readOnly/idempotent/non-destructive, yet the description adds substantial behavioral detail beyond them: reveal-gated privacy rules (own notes only before reveal, authors only on named notes, vote totals only once revealed), workspace tier requirement, and differing content for health checks vs classic boards.

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?

It leads with the core action and then enumerates the return shape, which is justified because there is no output schema. The single dense paragraph is heavy and could be broken up, but nearly every clause carries information the agent cannot get from structured 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?

With no output schema, the description fully compensates by describing the returned structure (setup, stages, columns, topics, tallies, votes, proposals, actions, summary) and the privacy conditions under which portions are visible. For a 1-parameter read tool, nothing needed to call it correctly is missing.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema itself noting the uid comes from list_retrospectives. The description adds no syntax or format detail beyond what the schema already documents, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read a retrospective') and further disambiguates the two shapes it may return (new-model retrospective/health check vs classic board). It does not explicitly name a sibling like list_retrospectives, but the schema's parameter description ties it to that tool, so the purpose 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?

Gives a real prerequisite ('Requires a Pro or trial workspace') and explains the conditional context that selects which variant you get (new-model vs classic board), plus when privacy gating applies. It stops short of explicitly contrasting with list_retrospectives or create_retrospective, so it is context-rich but not a full when/when-not routing statement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds the return format (compact text representation with board bounds and per-element lines) and the auth requirement, which enriches beyond the annotations. No contradiction.

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 detailed but efficiently organized: purpose, output format with examples, usage note, and requirement. Each sentence contributes value; the format example is clear and compact. It's slightly long but justified given the need to specify the exact text representation.

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 specifies the return format, including the exact line structure for elements and connectors, and the significance of uids. It also covers the auth requirement. For a read tool with one parameter, nothing essential is missing.

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

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

Schema coverage is 100% for the single 'id' parameter, which the schema already describes as 'The unique identifier of the whiteboard'. The description does not add any extra semantic details about the parameter itself (e.g., format or source), so it meets the baseline but doesn't exceed it.

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

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

The description opens with a clear verb+resource ('Read a whiteboard') and immediately specifies the output format, distinguishing it from sibling tools like list_whiteboards (which lists boards) and write tools (create/update). The detailed format example leaves no ambiguity about what this 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?

It implicitly routes usage by noting that element uids from this read are the handles for every whiteboard write tool, suggesting when to call this (before writes). It also states the Pro/trial requirement. However, it doesn't explicitly contrast with list_whiteboards or state when not to use it, so it's not fully explicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral detail: sections are returned with total_count, results are capped at limit, summaries are ready for get_card / move_card / update_card, and a Pro or trial workspace is required. This goes well beyond what annotations convey.

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

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

The description is dense but well-organized: purpose first, then kind definitions, then filters, then output shape, then access requirement. Every sentence contributes necessary information and no filler 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?

With no output schema, the description carries the burden of explaining return shape, and it does: per-section summaries, capping at limit, and total_count. It also covers default behavior, filter values, downstream tool compatibility, and workspace entitlement, so an agent has enough to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the behavior of 'kind' ('all' returns every list as its own section), the per-section meaning of 'limit', and the literal 'unassigned' value for assignee_id. This goes beyond the schema's standalone descriptions without being redundant.

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: 'List the cards needing attention on a project's kanban board.' It clearly defines the three list kinds ('stuck', 'blocking', 'overdue') and distinguishes the tool from generic listing siblings by tying it to the product's Metrics pages. An agent can infer exactly what this tool returns and how it differs from list_cards or search_cards.

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: use this when you need attention lists on a project board, with explicit semantics for each kind and optional assignee filtering. It doesn't explicitly mention alternatives or when-not-to-use conditions, but the purpose is specific enough that misuse against siblings like list_cards is unlikely.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns with them. Going beyond annotations, it discloses that only active lists are returned, they are in display order, and the backlog is included with an empty-string id, which is useful edge-case 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 compact and front-loaded: it states the action and purpose first, then the critical return details Ø. Every sentence adds relevant information, and 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 single-parameter read-only tool, the description is complete: it explains why to use it, what it returns, the list ordering, and the special backlog entry. With no output schema, the return-value details are sufficient for an agent to use the tool correctly.

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

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

The schema already documents project_id with 100% coverageebb, so the description does not need to add much. The description refers to 'a project's kanban board' but does not elaborate on the project_id format or additional constraints beyond the schema, matching the baseline for high schema coverage.

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

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

The description starts with a clear verb and resource: 'List the lists of a project's kanban board.' It further specifies the exact purpose, resolving a valid move_card destination, and the return contents, which distinguishes it from other list_* 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 clearly frames the tool as a prerequisite for move_card by stating its output is 'usable as a move_card target.' This gives clear context for when to use it, though it does not explicitly name sibling alternatives or state 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 cover the read-only/idempotent safety profile, and the description adds real behavioral nuance beyond that: board display order (placement position descending), unknown-uid-matches-nothing semantics, inclusive due_date behavior, and the updated_since caveat that collection edits may not bump change time. That caveat is genuinely useful context an agent would otherwise get wrong.

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

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

One dense paragraph, but front-loaded with purpose, scope and ordering before filters and return shape. Every clause carries information; it is long only because the tool is genuinely rich, though it could be broken into shorter sentences.

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

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

For a 10-parameter list tool with no output schema, the description covers scope resolution, filter composition, ordering, pagination and the summary fields returned, so an agent has everything needed to call and consume it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: filters combine with AND, uid filters silently match nothing when unknown, and pagination semantics (limit default 50/max 100, offset, total_count as full filtered count). This exceeds what the schema alone conveys.

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

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

States a precise verb+resource ('List the cards of one kanban list'), including the fallback scope (project backlog when list_id is omitted/empty) and the ordering rule. An agent can distinguish it from search_cards and get_epic without opening either schema.

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

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

Explains when the backlog branch applies, how filters combine (AND), and routes cross-list epic queries to get_epic. It gives clear context for use but never explicitly contrasts against the closest sibling, search_cards.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying display order (position ascending), the Markdown nature of descriptions, and the included card counts and date fields.

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

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

Two sentences front-load the purpose and immediately state the return behavior. There is no filler, redundant restating of the name, or repeated schema 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?

Given there is no output schema, the description appropriately lists the key returned fields, including uid, name, description, dates, and card counts directly in the description. For a simple list tool with clear annotations and schema, 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 description does not need to re-document parameters. It adds no extra semantic detail about project_id or updated_since, 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 says exactly what the tool does: 'List a project's epics' for resolving epic uids before get_epic or card assignment. It clearly distinguishes itself from singular get_epic and other sibling tools by framing the list as an enumeration.

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 context: use it to resolve epic uids for get_epic and card assignment. It does not explicitly mention alternatives to avoid, but the intended use case is clear enough to guide selection.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond annotations by specifying the return format (uid, name, position) and ordering (display order, position ascending), which is valuable given the lack of an 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?

Two short, information-dense sentences: the first states purpose and usage, the second states return fields and ordering. Every clause adds value and there is no filler or repetition.

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

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

For a simple one-parameter read-only tool with no output schema, the description provides the essential details: what is returned, the field names, and the ordering. Combined with the annotations, an agent has everything needed to invoke it correctly and interpret 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 description coverage is 100% and the single required parameter project_id is already well documented in the schema. The description repeats 'project's labels' but does not add new parameter-specific 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 ('List a project's labels'), the resource, and the intended purpose (reusing taxonomy instead of creating near-duplicates). It also implicitly distinguishes itself from create_label by framing the use case as a pre-write lookup.

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 this tool: before card writes, to reuse existing labels rather than creating near-duplicates. It does not name alternatives directly, but the context strongly implies the contrast with create_label, making the usage context clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to add context, which it does: it discloses the access scope, the returned fields (uid, name, plan, role, url), and the pro/trial plan requirement for dependent tools. 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?

Three dense sentences each earn their place: the core action, the when-to-call rule, and the return shape plus plan constraint. No filler, no repetition of schema data, and the most important guidance is front-loaded.

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

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

For a zero-parameter discovery tool with no output schema, this description is complete: it tells the agent what the tool does, when to call it, what data comes back, and why that data matters (pro/trial plan dependency). Annotations cover the safety profile, 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?

The tool has zero parameters and the schema already covers everything (100% coverage), so the baseline is 4. The description adds no parameter semantics because there are none, but it compensates by documenting what the returned value contains, which is what the agent actually needs to interpret the tool's output.

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 ('List') and resource ('every workspace and project the token's user can access'), and immediately states the operational purpose: resolving the project uid that most other tools require. It clearly distinguishes itself from the many list_* siblings by emphasizing the workspace-plus-project scope and access boundaries.

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 an explicit trigger condition: 'Call this first whenever no project uid is known' and a practical anti-pattern ('never ask the user to paste one'). It does not explicitly name alternatives or when-not conditions, but for a discovery tool this is sufficient and no obvious alternative exists among the siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavioral substance beyond that: the membership rules differ between standard projects (every workspace member) and private ones (creator, owners/admins, explicitly added), and it enumerates the returned fields and role values. It does not mention pagination or permission requirements, which is the remaining gap.

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

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

Front-loads the core action, then moves to return values, then to consumer linkage — a sensible information hierarchy with no filler. The middle sentence is long and clause-heavy, which costs a little readability.

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 the burden of describing returns, and it does so fully (uid, full name, email, workspace role with enumerated values). For a single-parameter, read-only listing tool, nothing needed to call it correctly is missing.

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

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

Only one parameter, project_id, and schema description coverage is 100%, so the schema fully documents it. The description implies the project scoping but adds no syntax, format, or constraint detail beyond the schema; baseline 3 is appropriate.

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

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

Opens with a specific verb+resource ('List the members of a project') and immediately differentiates itself from list_projects by scoping to project membership. It also distinguishes two sub-cases (standard vs. private projects) that an agent would otherwise have to infer.

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

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

States the purpose-driven usage explicitly: resolve assignee uids 'instead of guessing names', and names the downstream consumers (create_card, update_card, create_epic, update_epic, create_roadmap_slot). No when-not or exclusion is given, but there is no real competing sibling, so the context is clear.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantially more: conditional behavior (new-model entries where the workspace has them, classic boards otherwise), a permission gate (Pro or trial workspace), and the fact that the response augments entries with the project's open_actions_count. That is real behavior beyond the structured hints.

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

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

Purpose and scope are front-loaded in the first sentence, and the second sentence's field enumeration is dense but justified given there is no output schema. The semicolon-heavy run-on sentences slightly reduce readability, but no sentence is wasted.

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

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

With no output schema, the description compensates by enumerating the returned fields (uid, name, kind, status, date, stage, template, facilitator, action counts, url) plus the added open_actions_count, and it states the workspace requirement. Nothing an agent needs to call it correctly is missing.

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

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

There is a single required parameter, project_id, and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, format, or constraint detail beyond what the schema already provides, which is the baseline-3 case.

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

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

States a specific verb and resource ('List a project's retrospectives') and immediately distinguishes two data shapes: new-model retrospectives/health checks versus classic retrospective boards. It names the sibling get_retrospective as the deeper alternative, so an agent can separate it from that tool without opening a schema.

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

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

Routes the agent explicitly: 'Use get_retrospective for the full picture,' which is an effective when-to-use-this-instead signal, and states the eligibility prerequisite ('Requires a Pro or trial workspace'). It does not spell out a hard when-not condition, so it falls just short of the top tier.

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, destructiveHint, and idempotentHint. The description adds the 200-slot limit and the default window behavior, which is beyond annotations. It also explains that overlaps are by design, reducing surprise. This adds meaningful behavioral context without contradicting 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 tightly written, front-loaded with the core purpose, and every sentence earns its place. It covers scope, behavior, limits, and requirements in a few sentences with no 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?

Given there is no output schema, the description explains what a slot is, the return cap, and the date window behavior. It also notes the workspace requirement. It doesn't specify sorting or field details, but for a list operation this is adequate. The description is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so parameters are well documented. The description reinforces the defaults (start_date defaults to start of month, end_date to start_date + 6 months) and clarifies the overlapping behavior. It adds context about the cap and workspace requirement that complements the schema rather than repeating it.

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

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

The description clearly states the action (list), the resource (roadmap slots), and the scope (a project's slots overlapping a date window). It also clarifies what a slot is and that overlaps are intentional, distinguishing it from sibling operations like create/update/delete. This is specific and 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 provides clear context for use: the default date window, the 200-slot cap with a hint to narrow the window, and the Pro/trial workspace requirement. While it doesn't explicitly name alternatives, the read-only nature is evident, and the guidance on when to call it (to list slots) is implicit and 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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations: the auth requirement (Pro/trial workspace) and the specific list of returned fields. It does not cover pagination or ordering, but these are not essential for a simple list tool.

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

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

Two concise sentences: the first front-loads the purpose and return fields, the second gives the alternative tool and the auth requirement. Zero 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 one-parameter list tool with annotations covering safety, the description fully covers purpose, output fields, the alternative for reading elements, and the auth prerequisite. There is no output schema, so the description's mention of 'uid, name, element count, url' fills that gap. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%; the only parameter project_id already has a description ('The unique identifier of the project'). The tool description mentions 'of a project' but does not add new semantics about the parameter format or additional constraints. With full schema coverage, 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 the exact verb and resource, 'List the whiteboards of a project', and enumerates the returned fields. It explicitly contrasts with get_whiteboard, saying 'Use get_whiteboard to read a board's elements', which clearly differentiates it from the closest 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 description gives a direct usage condition: it lists whiteboards, and when you need to read the elements of a board, it points you to get_whiteboard. It also states the prerequisite 'Requires a Pro or trial workspace', which is an explicit qualification for when the tool can be used.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description only needs to add context beyond that. It adds the scope of the result set, the display-order guarantee, the returned fields, and the workspace plan requirement, all of which help the agent predict 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 compact and front-loaded with the core action, then the return fields, then the downstream use cases and access requirement. Every sentence earns its place and no filler 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 one-parameter listing tool, the description is complete: it states the input, the output fields, the ordering, the downstream usage, and the access restriction. Although there is no output schema, the description itself fills in the return contract sufficiently.

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%: the only parameter, project_id, is already documented as the unique identifier of the project. The description adds no new semantic detail about the parameter itself, but the schema fully covers it, so 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 names a specific verb and resource ('List a project's whole wiki tree') and precisely scopes the output to folders and pages with uid, name, type, and parent_id in display order. This clearly distinguishes it from single-page tools like show_wiki_page and page-creation tools like create_wiki_page.

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 conveys exactly when it is useful: to resolve the page uid needed by show_wiki_page and to choose a parent_id for create_wiki_page. It also notes the Pro/trial requirement. It does not explicitly state when not to use it versus related list tools, but the purpose context is clear.

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

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

Beyond annotations, the description reveals important behavior: empty string list_id moves to backlog, position 0 is the BOTTOM because lists render top-down, and omitting position produces different defaults depending on the target list type. These are meaningful operational details that the annotations 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?

Four sentences deliver the core action, board-type restriction, special value guidance, position orientation, and default-position rules with no filler. The most important information 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 mutation tool with moderate complexity and no output schema, the description covers all invocation-critical details: allowed board type, rejected board type, special list_id value, position ordering, and default placement rules. An agent has enough information to select and call this tool correctly.

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

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

Schema coverage is 100%, and the schema already documents id, list_id, and position thoroughly, including the empty-string backlog behavior and position semantics. The description largely restates this information rather than adding new parameter 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: 'Move a card to a different list (or change its position within the same list).' It also distinguishes the tool by limiting it to kanban boards and explicitly rejecting retrospective cards, making it clear how this differs from sibling tools like move_retro_item.

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 when-to-use context: moving cards on kanban boards, and explicit when-not: retrospective board cards are rejected. It also explains the backlog empty-string behavior. It does not explicitly name an alternative tool for moving retrospective items, but the exclusion is clear enough for an agent to infer the boundary.

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 non-destructive mutation annotations, the description discloses stage restrictions, stale-conflict refusal via expected_updated_at, mixed-content restrictions, model-specific parameter behavior, and workspace prerequisite. These are exactly the behavioral constraints an agent needs before calling.

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

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

The description is dense but front-loaded and earns its length through conditional model behavior, error semantics, and parameter interactions. Every sentence carries operational information without 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 complex mutation tool with no output schema, the description covers the two operating modes, required prerequisites, conflict handling, stage restrictions, and parameter behavior. It is complete enough for an agent to call it correctly without external 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?

Although schema coverage is 100%, the description adds substantial meaning: it explains topic_id as grouping into a topic, column as creating a topic at a position, expected_updated_at as a concurrency guard, and how parameters differ for classic versus new-model boards. This goes well beyond the schema text.

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

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

The description gives a specific verb and resource, 'Move a retrospective item', and immediately distinguishes the two supported retrospective models. An agent can tell this is not a generic card move but a retro-item regrouping/column-move 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?

It states exactly when each behavior applies: new-model retrospectives use topic_id/column grouping only in Group stage, while classic boards use column and position. It also gives refusal conditions (wrong_stage, stale) and the Pro/trial prerequisite, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is a validation step that returns 'server-computed consequences plus the preview_token', and it explicitly states 'Nothing is modified'. It also discloses the content format constraint (AHM: no tables, colors, alignment, discussions, or file attachments). The only minor gap is not describing what the server-computed consequences look like, but the description carries substantial behavioral weight 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?

The description is a single dense paragraph that front-loads the most important fact ('REQUIRED first step') and the core behavior ('validates... returns...'). Every sentence earns its place: the first sentence covers purpose and output, the second covers safety and content format, and the third covers prerequisites. It is slightly long but information-dense, and the structure is logical. It could be split into two sentences for readability, but it is not bloated.

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 validation tool with no output schema, the description explains the purpose, the required inputs' provenance, the content format, and the relationship to update_description. The main missing piece is a description of the return value shape (what 'server-computed consequences' looks like), but the description explicitly names the preview_token as the key output and points to get_ahm_spec for format details. Given the tool's complexity (4 required params, nested operations array) and the absence of an output schema, the description is nearly 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 description coverage is 75%, so the schema already documents most parameters. The description adds meaning by explaining the provenance of document_version ('from get_card / get_epic') and the source of block ids, which is not in the schema. It also clarifies that operations are 'applied in order against the evolving description', which adds semantic context to the operations array. The description does not repeat parameter names, and it compensates for the 25% gap by explaining where the required values come from.

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 ('validates'), a specific resource ('card or epic description edit'), and its role as the 'REQUIRED first step' before update_description. It clearly distinguishes itself from the sibling update_description by explaining it returns the preview_token that update_description requires. The scope is unambiguous and an agent can tell it apart from other preview/update tools without opening the schema.

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

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

The description explicitly says when to use it ('REQUIRED first step of every card or epic description edit'), what it does not do ('Nothing is modified'), and what prerequisites exist ('read get_ahm_spec first; block ids and document_version come from get_card / get_epic'). It also names the dependent sibling (update_description) and the source tools for required parameters. This is explicit when/when-not guidance with alternatives and prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: 'Nothing is modified', it returns a preview_token required by update_wiki_page, it lists the specific consequences (blocks added/removed/changed, files permanently deleted, discussions losing anchors, markdown warnings), and it notes the Pro/trial workspace requirement. It doesn't contradict annotations. The only minor gap is not detailing the exact response shape, but with no output schema and rich behavioral disclosure, a 4 is appropriate.

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

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

The description is dense but every sentence earns its place: it states the required-first-step role, lists the returned consequences, names the required token, clarifies non-mutation, gives the operation types and content format, names prerequisite tools, and states the workspace requirement. It is front-loaded with the most important usage constraint ('REQUIRED first step') and has no filler.

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

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

For a preview/validation tool with 3 fully documented parameters, no output schema, and annotations covering safety, the description is complete. It tells the agent what the tool returns (consequences + preview_token), what it doesn't do (nothing modified), what prerequisites are needed (get_ahm_spec, show_wiki_page), and when consequences are acceptable. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (id, document_version, operations) and their nested properties. The description adds context by explaining that operations are block-addressed with AHM content and that document_version comes from show_wiki_page, but it doesn't need to repeat schema details. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('preview'), a specific resource ('wiki page update'), and its role as the REQUIRED first step. It distinguishes itself from update_wiki_page by explaining it validates operations and returns consequences plus a preview_token, and it names sibling tools (get_ahm_spec, show_wiki_page) for prerequisites. This clearly differentiates it from siblings like preview_description_update and update_wiki_page.

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: 'REQUIRED first step of every wiki page update' and 'Review the consequences before saving'. It also gives exclusions/conditions: 'a listed file deletion or discussion unanchoring is only acceptable when the user asked for it' and 'Requires a Pro or trial workspace'. It names alternatives/prerequisites: read get_ahm_spec first, get block ids + document_version from show_wiki_page. This is explicit when/when-not guidance.

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

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

With readOnlyHint=true, idempotentHint=true, and destructiveHint=false already in annotations, the description adds valuable context: the checks are deterministic, findings are advisory and not errors, a board with findings may be exactly what the user wants, and a Pro or trial workspace is required. It also sets expectations about not looping. 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?

Every sentence earns its place: purpose, specific checks, advisory interpretation, usage guidance, and license requirement. It is front-loaded with the primary action and has 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?

This is a one-parameter tool with no output schema, and the description covers the checks performed, advisory nature, usage timing, and workspace requirement. The only gap is that it does not explicitly describe the return format, but for a deterministic review tool with simple input, 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 coverage is 100% because the only parameter, 'id', has a full description in the schema. The tool description does not add detail about the parameter itself, but it doesn't need to; the baseline of 3 applies when the schema already documents parameters thoroughly.

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: 'Run deterministic quality checks on a whiteboard', then enumerates concrete checks (text overflow, overlapping elements, unbound connectors, palette violations, off-grid positions, orphaned elements). This clearly distinguishes it from sibling tools like get_whiteboard, which fetches state, and list_whiteboards, which lists boards.

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 it ('Use after drawing to sanity-check') and gives strong behavioral guidance ('fix at most once, and do not loop chasing an empty report'). It does not explicitly name alternatives or when-not-to-use conditions, but the advisory framing and placement guidance provide clear enough 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 and idempotentHint, and the description adds substantial behavioral context beyond that: relevance ranking with recency boost, result shape including type/uid/url/snippets, action-ready uid mappings to other tools, and total_count semantics. No contradictions with annotations exist.

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 information-dense but well-ordered: scope first, then usage guidance, then result semantics, then optional parameters and pagination. Every sentence earns its place with no filler or repetition of the schema.

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

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

With no output schema present, the description compensates by enumerating what each result carries and how the uid can be used with specific tools. Combined with the annotations and sibling differentiation, nothing essential is missing for an agent to call this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by explaining that project_id and assigned_to_me are optional scoping filters, and by connecting page/per_page to total_count as the full match count, going slightly beyond the bare schema definitions.

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: 'global full-text search (OpenSearch)' across named entity types and fields. It also explicitly differentiates itself from search_cards, making the tool's scope unmistakable.

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 an explicit usage instruction with a concrete example ('find anything by content') and an exclusion condition: use search_cards only for title-substring lookups inside one project. This leaves no ambiguity about when to select this tool over its 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 declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond that: newest-created-first ordering, empty array instead of error on no matches, pagination semantics, and total_count meaning. This is exactly the kind of contextual behavior that helps an agent trust and interpret results.

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

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

The description is dense and front-loaded with the core purpose, and every clause carries behavioral value. It is slightly long and contains minor redundancy between 'Title-substring' and 'database case-insensitive substring on the card title only', but it remains well-structured for the nuance it conveys.

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 still provides the return shape ('action-sufficient card summaries' with key fields), ordering, pagination parameters, and empty-result behavior. An agent has enough information to invoke the tool and correctly interpret its 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?

The input schema has 100% description coverage, including defaults, ranges, and matching semantics. The description reinforces pagination and the no-match result but does not add significant parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ('search'), a precise resource scope ('within one project', kanban board and backlog), and the exact matching criterion ('case-insensitive substring on the card title only'). It explicitly distinguishes itself from the search tool and clarifies what it does not cover (descriptions and comments), so agents can tell it apart from siblings 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 direction: use this tool for title-only card search within a project, and use the search tool when full-text search across all content types is needed. It also communicates scope constraints and the exact matching behavior, making the selection decision clear. The main alternative is explicitly named.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the content is AHM not markdown, block ids and discussion anchors are part of the document, and the returned document_version is needed for subsequent edits. It doesn't describe pagination or error cases, but for a single-resource read with strong annotations, this is solid.

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

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

Three sentences, each earning its place: what the tool returns, what the content format implies, and how to use the result for editing. The most important information (AHM format, document_version) is front-loaded, and the workspace requirement is a useful final note.

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

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

For a single-parameter read tool with strong annotations and no output schema, the description covers everything an agent needs: what it returns, the format caveat, the prerequisite spec, the edit workflow, and the workspace requirement. No output schema exists, but the description explains the key return values (AHM content, document_version) sufficiently.

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

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

Schema coverage is 100% and the single parameter 'id' is described as 'The unique identifier of the page path'. The description doesn't add much beyond that, but with only one parameter and full schema coverage, the baseline of 3 is appropriate. The description does imply the id is a page path, which slightly reinforces 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 retrieves a wiki page as AgileHero Markup (AHM) with its document_version, and explicitly distinguishes AHM from markdown. It names the specific resource (wiki page) and the format (AHM), making it distinct from siblings like get_ahm_spec and update_wiki_page.

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 to read get_ahm_spec before editing, and to edit via preview_wiki_page_update then update_wiki_page using the block ids and document_version returned here. It also states the Pro or trial workspace requirement, giving clear context for 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?

The annotations already mark destructiveHint=true and readOnlyHint=false; the description goes further by enumerating which fields (labels, assigned_to, checklists, cards_relations, links, attachments) replace state destructively and by flagging the incompatibility with delta fields. It adds genuine behavioral context beyond the annotations, such as safe incremental edit semantics and exact-match/no-op removal behavior.

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

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

Three sentences with the core purpose front-loaded ('Update an existing card by its uid'), followed by the highest-risk guidance and sibling routing. There is no filler, and the wording is dense but readable, earning its place for a 24-parameter tool.

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 complex, destructive-capable mutation, the description covers the principal risk (replace vs delta), compatibility constraints, and sibling routing. Minor gap: it never explicitly states partial-update semantics (fields not provided are left unchanged), which is inferable but not stated, and there is no output schema describing 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?

With 88% schema coverage, the schema already documents most parameters, so the baseline is 3. The description adds an organizing semantic layer: it classifies collection fields into safe delta operations versus destructive replacement fields and states that they cannot be combined, which goes beyond what individual schema entries convey.

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

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

States a specific verb and resource: 'Update an existing card by its uid.' It distinguishes itself from siblings by naming move_card and the description-update tools, making it clear this tool handles card field updates rather than position or description edits.

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 the agent to prefer add_*/remove_* delta fields for collections as 'safe incremental edits' and warns that plain collection fields 'REPLACE the prior state destructively and cannot be combined with their deltas.' It also names the alternatives move_card, preview_description_update, and update_description for other concerns, leaving no ambiguity about when to use 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 signal destructive, non-read-only, non-idempotent behavior with destructiveHint=truedar. The description adds valuable context by explaining the strict contract: the preview_token is tied to EXACTLY these operations and this document_version, and a save cannot happen without previewing. It also discloses the return value (updated description plus new document_version).

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?

Both sentences earn their place: the first states the action and target, the second adds the critical prerequisite and return value. The text is front-loaded and free of filler.

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

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

For a five-parameter mutation tool with no output schema, the description covers the key workflow context, the mandatory preview step, and the return data. It does not discuss error conditions or the exact AHM format, but annotations and schema already provide a solid baseline for a tool with this specificity.

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

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

With 80% schema description coverage, the input schema already documents the parameters and their roles. The description reinforces that operations and document_version must match the preview exactly, but it adds little beyond what the schema already conveys about the token source and version semantics.

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

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

The description clearly states a specific verb+resource: apply a previously previewed description update to a card or epic. It distinguishes itself from generic update_card/update_epic by emphasizing the mandatory preview_token prerequisite and the two-step workflow.F

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 names preview_description_update as the source of the required token and states that saving without previewing is impossible, which communicates when this tool must be used. It does not explicitly exclude generic update_card/update_epic as alternatives, but the preview requirement effectively does so.

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 carry destructiveHint=true, but the description adds crucial behavioral context: partial updates are applied per-field, plain collection fields replace the entire prior state, and delta fields are non-destructive and incompatible with their plain counterparts. This meaningfully enhances what the annotations alone convey and does not contradict them.

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

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

Three dense sentences deliver the essential information without padding: partial update behavior, destructive replacement warning, delta-field preference, and a pointer to description-edit tools. The most important caveats are front-loaded and each 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 tool's complexity (17 parameters, destructive behavior, no output schema), the description covers the main hazards an agent must know: which fields replace versus increment, the constraint against mixing them, and where to route description edits. The annotations and rich schema descriptions fill the remaining detail, making this complete enough 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 high (94%), so individual parameters are already well documented. The description adds group-level semantics by categorizing fields into plain replacement fields versus add_*/remove_* delta fields and warning about their incompatibility, which goes beyond the per-parameter schema descriptions.

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

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

The description states a clear action ('Update an existing epic'), identifies the resource by uid, and clarifies partial-update semantics ('only supplied fields are changed'). It also distinguishes the tool from description-editing siblings by explicitly routing those to preview_description_update / update_description.

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 when-to-use guidance: prefer add_*/remove_* delta fields for safe incremental edits, avoid plain collection fields because they destructively replace prior state, and never combine plain fields with their deltas. It also names the alternative tools for description edits, leaving no ambiguity about selection.

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 indicate readOnly=false and destructive=false, so the description carries the burden of explaining mutation behavior. It clearly discloses the non-obvious replace semantics of assigned_to and the 'same project' constraint for epic_id, adding meaningful context 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 front-loaded with the primary purpose, then organized by operation. Every sentence adds necessary behavioral or prerequisite information without unnecessary filler, and the critical exception is highlighted with an uppercase emphasis.

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

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

For a mutation tool with no output schema and annotations that don't disclose effects, the description covers the essential behavioral rules, prerequisites, and id source. It does not describe the return value or possible errors, but those are less critical given the clear operational scope.

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 parameters are already documented. The description adds key semantic detail beyond the schema: epic_id must belong to the same project, assigned_to REPLACES all assignees with [] clearing, and unspecified fields remain unchanged. This improves an agent's ability to call the tool correctly.

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 uses a specific verb and resource ('Update a roadmap slot') and immediately enumerates the allowed operations: reschedule/resize dates, move to another epic, and set assignees. This clearly distinguishes it from create_roadmap_slot and delete_roadmap_slot among 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?

Provides explicit operational guidance: 'Only supplied fields change', warns that assigned_to replaces the full assignee set, advises reading the slot first, and notes the Pro/trial workspace requirement. It does not explicitly contrast with alternative update tools, but the update semantics are unambiguous 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 are minimal (only readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden and delivers: atomicity ('all-or-nothing'), field-level preservation ('Only supplied fields change — unrelated properties are preserved'), reparent semantics ("" to detach), the immutability of element types, and the Pro-or-trial entitlement. This is substantial value beyond the annotations, with no contradiction.

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

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

The core action and key constraints are front-loaded in one dense, information-rich sentence followed by two short constraint statements. Every clause earns its place — no filler, no repetition of schema content, and the most decision-relevant facts (type immutability, Pro requirement, preservation semantics) are stated compactly.

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

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

For a mutating batch tool with no output schema, the description covers the essential operational aspects: batch size limit (from schema, reinforced as 'up to 100'), atomicity, preservation of unspecified fields, source of uids, type immutability, and workspace tier. Minor gaps remain around failure behavior for invalid uids and the exact return value, but nothing an agent critically needs to invoke it correctly.

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

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

Schema coverage is only 50%, but the description compensates by mapping every operation to its parameters: move (x/y), resize (width/height), restack (z_index), recolor (color with hex-fill and auto re-derived borders), reparent (parent_id with detach semantics), and connector path/arrow/label. This adds meaning beyond the raw schema, though individual parameter details like z_index ordering or numeric bounds are not described.

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

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

States a specific verb+resource ('Update up to 100 whiteboard elements in one all-or-nothing call') and enumerates exactly what can be changed (move, resize, restack, retext, recolor, reparent, connector properties). It also names the key limitation ('element types cannot be changed'), which distinguishes it from sibling tools like convert_whiteboard_element and create_whiteboard_elements.

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

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

Provides clear operational context: uids come from get_whiteboard, and a Pro or trial workspace is required. It states the constraint that element types cannot be changed but doesn't explicitly name the alternative tool for that scenario, so it stops short of full when-to-use-vs-alternatives 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 mark the tool as destructive; the description adds meaningful context without contradicting them: every save creates a revertible page version, the save is restricted to the exact previewed operations and document_version, and the response includes the updated page and applied consequences. It also mentions the workspace tier requirement. This is exactly the kind of added behavioral transparency expected when annotations are present.

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

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

Four short sentences front-load the purpose, then state the key constraint, side effect, return value, and prerequisite. Every sentence carries necessary information with no filler or repetition.

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

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

Despite no output schema, the description covers return content (updated page with AHM and new document_version, plus applied consequences), the preview requirement, versioning behavior, and workspace eligibility. Given the tool's complexity and destructive hint, this is complete enough for an agent to invoke it correctly and anticipate 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?

The input schema already documents each parameter and covers 100% of them, so the baseline is 3. The description adds cross-parameter semantics: the preview_token must match EXACTLY the supplied operations and document_version, and saving without a preview is impossible. This relationship between parameters is not in the schema and materially improves correct usage, so a 4 is warranted.

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

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

The opening sentence, 'Apply a previously previewed update to a wiki page,' uses a specific verb and resource, and the qualifier 'previously previewed' immediately distinguishes this from preview_wiki_page_update. It also names the update, versioning, and workspace requirements, leaving 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 makes the workflow clear: it must follow preview_wiki_page_update and requires its preview_token. It explicitly states that saving without previewing is impossible by design and that a Pro or trial workspace is required, which are important usage conditions. However, it does not explicitly name alternative tools or situations where one should not use this tool, so it stops 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.