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

Description discloses behavior beyond annotations: notes appended under '## Notes' section with ISO 8601 timestamp, return structure {story_id, appended_at, path}. It is consistent with destructiveHint=true and idempotentHint=false.

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

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

Three efficient sentences cover action, use cases, and behavior/return. No wasted words, front-loaded with key 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?

Complete for a simple append tool with 2 params and no output schema. Could mention prerequisite (story must exist) but not essential given context signals and sibling tools.

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

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

Schema covers both parameters with descriptions. Description adds meaning: notes are multi-line, stored with UTC timestamp, under specific section, and return fields. No ambiguity.

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 clearly states the action 'append a timestamped note to a story file' and specifies resource (story file). It distinguishes from sibling tools which handle other operations like creating stories or updating statuses.

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?

Description explicitly says 'Use to record progress, decisions made, or blockers encountered', providing clear use cases. However, it does not explicitly state when not to use or mention alternative 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?

Discloses partial update behavior, exact match, atomicity (no changes on mismatch), and return shape. Annotations already indicate mutability and destructiveness, but description adds context beyond that.

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

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

Four sentences, each with distinct information. Front-loaded with main action. 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?

Adequately covers all aspects given no output schema. Return format specified. Could add more on success behavior but 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%, but description explains exact matching, boolean meaning, and partial update semantics. Adds value beyond 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?

Clear verb+resource: 'Update the checked state of individual acceptance criteria on a story'. Distinguishes from siblings like check_acceptance_criterion (single) and set_acceptance_criteria (setting list).

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

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

Tells when to use (bulk update) and behavior: only listed criteria modified, exact match required, error if not found. Suggests using get_story to see results. Lacks explicit sibling differentiation but context permits.

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 destructiveness, and the description adds valuable context: atomicity per file, error handling on missing epics, and structure of return results. This goes beyond what annotations provide.

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

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

Description is concise with three sentences, front-loads purpose, and covers key behaviors. Efficient but could be slightly more streamlined.

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

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

Given no output schema, the description adequately explains return format. Annotations cover safety. Missing details on prerequisites or rate limits, but overall sufficient for a bulk update tool.

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

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

Schema coverage is 100% and already explains parameter details (required fields, status enum, note behavior). The description merely echoes 'Each entry may set status and/or append a note', adding negligible new 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 clearly states the tool updates multiple epics in one operation, specifies actions (set status, append note), and addresses error handling. It distinguishes from single-epic tools like set_epic_status and create_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?

The description implies use case for bulk updates but does not explicitly state when to prefer this over single-update siblings (e.g., set_epic_status). Lacks 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 declare destructiveHint=true, and description adds that non-existent stories result in errors but processing continues. It also mentions atomicity per file. Does not contradict annotations; adds useful behavioral detail beyond what annotations provide.

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

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

Single paragraph, dense but well-organized. Front-loads purpose, then details. Slightly verbose in the criteria description, but overall efficient for the complexity.

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

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

Covers all key aspects: what is updated, input format, atomicity, error handling, and return array structure. No output schema, but description adequately describes the per-story result objects. Given the tool's complexity, the description is fully adequate.

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%, but description adds critical meaning: enumerates valid statuses (draft, in-progress, blocked, deferred) and notes 'complete_story' for done. For criteria, explains it's a map with case-insensitive matching and Unicode dash tolerance. This goes well beyond the schema's minimal 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?

Clearly states 'Update multiple stories in one operation' and lists the fields that can be updated (status, note, criteria). Distinguishes from siblings like 'complete_story' by explicitly mentioning when to use that sibling. Also describes atomicity per file and error handling.

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 guidance on status values and directs to 'complete_story' for marking done. Implicitly indicates this tool is for bulk updates, but does not explicitly state when not to use it or provide alternatives for single story updates.

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 (destructiveHint=true, idempotentHint=false), the description discloses specific error conditions (story not found, criterion not found, already checked) and the return format, adding concrete behavioral context.

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

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

Two concise sentences: first states action and transformation, second covers identification, return values, and errors. No redundant fluff; 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?

The description, combined with annotations and schema, fully covers purpose, usage, parameters, behaviors, and error states. No additional information is needed for correct invocation.

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

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

The input schema already has 100% coverage with good descriptions. The description adds value by explicitly stating 'Exactly one must be provided' for the mutually exclusive parameters, reinforcing the constraint.

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

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

The description uses a specific verb 'Mark' and resource 'acceptance criterion' with a clear transformation '- [ ] → - [x]'. It distinguishes from sibling tools like bulk_update_acceptance_criteria and set_acceptance_criteria by focusing on a single criterion.

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 specifies how to identify the criterion (index or text, exactly one required) and lists error conditions. It implies single-criterion use but does not explicitly contrast with bulk alternatives; however, the context of sibling tools makes the distinction 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?

While annotations already mark destructiveHint=true and readOnlyHint=false, the description adds critical context: removal from backlog.md, return fields, blocking behavior when AC not set, and conditional requirement for incomplete_items. Does not contradict annotations. Deduction for not explicitly stating error behavior beyond blocking.

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

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

The description is concise (about 6 sentences) and front-loads the core action. Every sentence adds value, but it packs many conditional rules into a single paragraph. Slight improvement possible with structured list for key constraints.

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 (validation, conditional parameter, destructive side effects, no output schema), the description covers: purpose, preconditions (AC set, proper tick marking), conditional field usage, success effects (backlog removal, return values). No output schema, but return values are described. Completeness ensures an agent can use 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 has 100% coverage with descriptions, but the description adds significant meaning: explains when incomplete_items is required vs prohibited, and that summary is timestamped. Goes beyond baseline of 3 by clarifying conditional logic and constraints not fully captured in 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's purpose: 'Mark a story done and append a mandatory completion summary note in one atomic call.' It specifies the verb, resource, and action. It also distinguishes itself from siblings by mentioning validation of acceptance criteria and the need to call set_acceptance_criteria first.

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 guidance: explains when to use set_acceptance_criteria first, when incomplete_items is required, and what constitutes proper usage. Contrasts with sibling tools like set_acceptance_criteria. Clearly states when-not-to-use for incomplete_items field.

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 destructive hint true; description adds detail on side effects: ID assignment, directory/file creation, index registration. Adds context beyond annotations without 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 sentences: purpose then action sequence and return value. No fluff, front-loaded with key 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?

Covers return value and side effects comprehensively for a create operation. Lacks error conditions but acceptable given annotations and schema richness.

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%; description adds value by noting the description parameter is written into epic.md file. Otherwise aligns with 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?

Clearly states the action 'Create a new epic' and the resource. Distinguishes from siblings like 'create_story' and 'bulk_update_epics' by specifying it creates a single epic with ID assignment and file 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?

Provides no explicit when-to-use or alternatives. Implicitly for creating a single epic, but no guidance on when to use this versus sibling tools like 'create_story'.

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 (destructiveHint=true), the description explains the exact side effects: ID assignment, file writes, registration in two files, and appending to backlog. No contradiction with annotations.

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

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

Two sentences, front-loaded with the main action, followed by essential details. Every sentence is informative and no fluff.

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

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

The description covers the return value, preconditions (epic exists), process steps, and side effects. It does not address error handling or constraints on title/description length, but it is sufficient for most use cases.

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 parameter descriptions. The description adds value by explaining that the description parameter is written into story.md and that epic_id must already exist. It also reveals the ID assignment mechanism 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 clearly states the verb 'create', the resource 'story', and the context 'under an existing epic'. It distinguishes from sibling tools like create_epic by specifying the parent requirement. The details on ID assignment and file registration further clarify the action.

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

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

The description implies the epic must exist and the story will be placed into the backlog. It does not explicitly say when not to use this tool or mention alternatives, but the name and context make it clear this is the primary tool for creating stories.

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 describes a read-only operation ('Get a high-level summary'), but the annotation destructiveHint=true indicates the tool may cause destructive side effects. This is a direct contradiction. Additionally, no other behavioral traits (e.g., authentication requirements, side effects) are disclosed beyond what annotations provide, which is insufficient for a tool with contradictory annotations.

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

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

The description is two sentences, front-loaded with the core functionality, and includes both usage context and return format. Every sentence is informative and concise, with no waste.

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

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

The description details the return format, compensating for the lack of an output schema. It also provides usage context. However, it does not address the contradiction with the destructiveHint annotation, leaving uncertainty about side effects. For a simple zero-parameter tool, this is a noticeable gap that impacts completeness.

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

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

There are no parameters, so the input schema is fully covered. The baseline score of 4 applies as per the rule for 0 parameters. The description does not need to add parameter information, and it does not attempt to.

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

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

The description clearly states the tool provides a high-level summary of all epics with story counts by status. It specifies the action (Get), the resource (epics summary), and the scope (all epics, broken down by status), which distinguishes it from sibling tools that focus on individual items or mutations.

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 it is 'useful for situational awareness at the start of a session, without reading every file,' providing clear guidance on when to use it. However, it does not mention alternatives or explicitly state when not to use it, which would strengthen the 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?

The description explains that the tool returns content and how include_notes alters the returned content. However, the annotations indicate destructiveHint:true, implying potential modification, which contradicts the read-only nature described. This mismatch reduces transparency.

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

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

Two sentences, front-loaded with purpose. Every sentence adds value without redundancy. Concise and well-structured.

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?

Provides return structure and behavior of include_notes. No output schema, so description compensates. However, the destructiveHint annotation inconsistency is not addressed, leaving a gap in completeness about the tool's true effect.

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 covers both parameters (100% coverage). The description adds context for include_notes: omitting the '## Notes' section and everything after it, which is not evident from the schema alone. This enhances understanding of the parameter's effect.

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: 'Get the full markdown content and metadata for a single story.' It also lists the return fields (story_id, title, status, epic_id, path, content), making it distinct from sibling tools like list_stories or add_story_note.

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?

Describes when to set include_notes=false ('when you only need current status, goal, or acceptance criteria and want to avoid paying for a long accumulated note history'). Provides clear context for using this parameter, though no explicit when-not-to-use or alternative tools are mentioned.

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

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

Annotations mark the tool as destructive, and the description confirms modifications (adds, removes, refreshes). It provides context beyond annotations by detailing what is changed (epic.md sections) and the return object. No contradictions.

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

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

The description is two sentences, front-loaded with the main action, and uses precise language. Every sentence adds value without 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 single-parameter tool with no output schema, the description adequately covers the operation and return structure. It could mention prerequisites (e.g., file existence) but is sufficient for correct invocation.

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

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

The schema covers 100% with a description for epic_id. The tool description does not add additional semantics beyond reiterating the parameter's use. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: reconciling the Stories section in an epic.md file with story files on disk and the requirements index. It specifies exactly what it does (add, remove, refresh) and the return value, which distinguishes it from all sibling tools.

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

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

The description implies when to use the tool (to synchronize epic file with disk state) but does not explicitly state when not to use it or mention alternatives. However, given the unique purpose, the agent can infer appropriate usage.

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 describes a read operation (list stories), but annotations mark destructiveHint=true, suggesting potential mutation. This contradiction is critical and not addressed.

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 sentence with a clear structure, front-loading purpose and adding return format and sibling tools efficiently.

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

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

Despite no output schema, the description specifies the return format and covers all necessary information for a filtering list tool.

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

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

The description adds default behavior context (returns all stories when no filters) beyond the schema, which already covers parameters well (100% coverage).

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

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

The description clearly states the tool lists stories from the project index with optional filters, and distinguishes from siblings like get_story and get_index_summary.

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 indicates when to use (listing stories, with or without filters) but does not explicitly exclude alternative tools or provide guidance on when not to use.

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

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

The description goes beyond annotations by detailing that entries omitted from story_ids are appended at the end, that not-found IDs are reported without causing failure, and that the response includes placed, not_found, and appended lists. This adds significant context to the destructiveHint=true and readOnlyHint=false annotations.

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

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

Two sentences with no wasted words. The first sentence states the action, the second explains details and return values. Information is front-loaded and every sentence contributes.

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 single parameter, no output schema, and existing annotations, the description fully explains the tool's behavior and return format. It covers what happens to all backlog entries, handling of not-found IDs, and the structure of 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?

The input schema describes story_ids as an ordered list of story IDs for backlog priority. The description adds that entries listed are placed first and omitted ones are appended, enhancing the semantic understanding beyond the 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 clearly states it reorders the active backlog by supplying a desired story ID sequence. It specifies the verb 'reorder' and the resource 'backlog', and details the behavior with omitted and not-found IDs, distinguishing it from siblings like 'set_story_status' or 'complete_story'.

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

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

The description explains what the tool does but does not explicitly state when to use it or when not to use it, nor does it mention alternatives among siblings. Usage is implied by the purpose, but no explicit guidance is given.

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

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

The description claims the tool is 'Idempotent', but the annotations set idempotentHint to false, creating a direct contradiction. Additionally, the description discloses behavioral details (checkmark preservation, AC-ID handling) beyond the annotations, but the contradiction severely undermines transparency.

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 well-structured, starting with the main action, then explaining the checklist format, idempotency, and a prerequisite. While it packs a lot of information, it remains clear and efficient, with each sentence serving a distinct purpose.

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 key aspects: what the tool does, how to format criteria, idempotency, prerequisite, and return value. However, the annotation contradiction (idempotentHint mismatch) introduces confusion, reducing overall completeness for a reliable agent decision.

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 provides 100% parameter descriptions, but the description adds significant value by explaining the checklist behavior: plain text becomes unchecked `- [ ] ...` items, and how to pass pre-checked items or preserve AC-IDs. This goes beyond the schema's basic 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 clearly states the tool's purpose: 'Replace the acceptance criteria section of a story file.' It elaborates on the format of criteria strings, idempotency, and the prerequisite relationship with complete_story, making the function unambiguous and distinct from sibling tools.

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

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

The description explicitly states when to use the tool: 'Acceptance criteria must be set before a story can be completed with complete_story.' It also notes idempotency. However, it does not provide explicit exclusions or guidance on when not to use it versus alternative tools like bulk_update_acceptance_criteria or check_acceptance_criterion.

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 (destructiveHint: true), description details mutation behavior, guards for backwards transitions and incomplete stories, required summary for 'done', and return object.

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?

Well-structured with front-loaded purpose, then progression, status meanings, and guards. Every sentence adds essential information without 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?

Comprehensively covers conditional logic (required summary for done, guards for incomplete and regression), return structure, and all edge cases despite lacking 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?

Adds meaning beyond schema by explaining status meanings, typical progression, and contextual use of override_incomplete and confirm_regression.

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

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

The description clearly states the tool updates epic lifecycle status, distinguishes from set_story_status, and provides typical status progression.

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

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

Explicitly states when to use this tool vs alternatives (set_story_status) and provides detailed guards for override_incomplete and confirm_regression with user confirmation requirements.

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 destructiveness and non-idempotence; description elaborates on behavior (return values, backlog update) without 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, critical info front-loaded, no wasted words.

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

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

Given full schema, annotations, and description covering return format, no gaps remain.

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 good descriptions; description adds minimal extra meaning beyond what schema already provides.

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

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

Description clearly states it updates story status to four specific values and distinguishes from complete_story, making the tool's purpose 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?

Explicitly tells when to use this tool vs complete_story, including rationale for the alternative.

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