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

With no annotations, the description carries the full disclosure burden. It reveals a genuinely useful behavior — the tool can be invoked from any status, so no state preparation is needed — and defines the content contract for findings. It doesn't disclose reversibility or downstream effects on related items, but for a narrow 2-param mutation the core workflow behavior is transparent.

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

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

Two sentences with zero waste. The action is front-loaded and the em-dash clarification of findings earns its place, as does the status note. Every sentence adds information.

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

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

For a 2-parameter tool with an output schema carrying return-value info, the description is nearly complete: it covers the action, the content of findings, and status flexibility. The only gap is the post-condition — what state the spike ends in and whether the action is reversible.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning to findings ('the answer to the question it was investigating and any recommendations'), which is the parameter most likely to confuse an agent. But spike_id receives no semantic guidance beyond its name, and findings has no format or structure details, so compensation is only partial.

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 — 'Close a spike by recording its findings' — and further clarifies findings as 'the answer to the question it was investigating and any recommendations.' This clearly distinguishes the tool from siblings like complete_task without needing to open 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?

'Works from any status' is an explicit precondition note telling the agent that no status prerequisite check is required before calling. However, it doesn't name alternatives or state when-not-to-use it (e.g., when to prefer complete_task), so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that notes is a terse frontmatter one-liner and that a fuller summary should be written into the '## Completion Notes' body section separately. It also clarifies that the tool works from any status, which proactively prevents the agent from assuming a prerequisite. It does not detail side effects beyond status change, but it covers the key behavioral 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?

Three sentences, zero filler. The primary purpose is front-loaded, followed by parameter nuance and workflow guidance. Every sentence earns its place without redundant restatement of the tool name or schema.

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

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

For a simple two-parameter tool with an output schema present, the description is complete: it defines the action, explains the notes parameter, clarifies the optional prerequisite, and tells the agent the next step. No critical context for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for notes by specifying it is a 'terse one-liner for the frontmatter field' and directing fuller details elsewhere. task_id is left to inference, but its purpose is obvious from the name and the required-parameter context.

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: 'Mark a task as completed with notes on what was done.' It clearly distinguishes this from sibling workflow tools by framing itself as the middle step between start_task and verify_task, so an agent can identify its role without ambiguity.

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

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

The description provides explicit sequencing context: 'Ideally call start_task first, but this works from any status' and 'After this, call verify_task with evidence to finalise.' This tells the agent when in the workflow to use the tool, but it does not explicitly state when not to use it relative to complete_spike or update_ticket.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses that this creates a persistent spike entity under an existing story, that the story must already exist, and that the spike has a lifecycle ending with complete_spike. It doesn't detail failure modes or authentication, but the essential behavior is transparent.

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

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

The description is two sentences with no wasted words. The core action and definition are front-loaded, and the second sentence adds the essential prerequisite and follow-up step. Every sentence contributes useful information.

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

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

For a simple create tool with four scalar required parameters and an output schema, the description covers the key context: what a spike is, that it belongs under an existing story, and what to do after completion. Minor gaps such as the expected format for timebox are not critical given the output schema and self-explanatory parameter names.

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

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

Schema description coverage is 0%, so the description must compensate. It maps well to the parameters: 'under a story' implies story_id, 'timeboxed' implies timebox, and 'answer a specific question' implies question. Title is less explicitly addressed but is self-explanatory as a parameter name. The semantic mapping is sufficient for an agent to construct valid arguments.

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 and resource: 'Create a Spike under a story', and defines what a Spike is ('a timeboxed investigation to answer a specific question'). This clearly distinguishes it from create_story and other sibling tools, and the phrase 'under a story' establishes the hierarchy.

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 invocation context: the parent story must already exist, and when the spike is done, complete_spike should be called with findings. It does not explicitly name alternatives or when-not-to-use cases, but the prerequisite and follow-up provide enough guidance for correct 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?

With no annotations provided, the description carries the full burden and delivers: prerequisite validation (epic must exist), a non-blocking warning behavior for missing ADRs, a hard validation constraint ('Each ADR must exist and belong to the same epic'), and the post-creation contract to pause for user agreement. This goes well beyond the generic 'Create a Story' phrase.

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

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

Three tight paragraphs with no filler; each sentence carries operational value and the core purpose is front-loaded. The final paragraph is more agent-workflow instruction than tool description, but it earns its place by preventing premature task creation. Slightly long, but justified for the tool's workflow 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?

An output schema exists, so return values need no explanation. The description covers prerequisites, validation, parameter semantics for the most complex param, and follow-up workflow. Remaining gaps: the meaning of `what` and `definition_of_done`, and no explicit contrast with create_spike for when a spike is the right artifact instead of a story.

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

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

Schema description coverage is 0%, so the description must compensate. It explains adr_ids well (purpose plus existence/same-epic validation) and lightly covers epic_id and acceptance_criteria. However, the required `what` parameter and optional `definition_of_done` are completely unexplained, leaving an agent to guess their content.

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, 'Create a Story under an epic — a deliverable with acceptance criteria,' states a specific verb plus resource and defines what a Story is. This clearly differentiates it from siblings like plan_epic, create_task, and create_spike with minimal effort.

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 routing: 'if one hasn't been created yet, call plan_epic first.' It also discloses the conditional when ADRs are missing ('the story is still created') and the required follow-up workflow (present plan, wait for agreement before creating tasks). An agent knows exactly when and in what sequence to call 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?

With no annotations, the description carries the behavioral burden. It discloses that the parent story must already exist and that task creation should be followed by presenting the task list, not immediate implementation. However, it does not mention possible side effects beyond creation, failure behavior, permissions, or whether results are persisted, which a state-changing tool with no annotations could usefully state.

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

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

The description is three short paragraphs with no filler. The core purpose is front-loaded, followed by the prerequisite, workflow constraint, and bug-fix policy—each sentence adds operational value.

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

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

For a creation tool with four required parameters and no parameter descriptions, the description covers the essential context: what a task is, that a story must already exist, the expected workflow, and when to prefer a task over a new story. Because an output schema exists, return-value detail is not required. It could be more complete by explicitly contrasting with create_spike, but the implementation-focused definition largely covers that.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly clarifies story_id (parent story must exist), what_to_do (implementation work), and testable_outcome (testable outcome), but it never maps these concepts to the parameter names or explains expected formats. Title is left entirely to its self-evident name.

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

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

The description opens with a specific verb and resource: 'Create a Task under a story.' It adds a precise definition—'a concrete unit of implementation work with a testable outcome'—which clearly distinguishes tasks from stories and spikes among the sibling tools.

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

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

The description gives an explicit prerequisite ('The parent story must already exist'), a workflow directive (present the task list before starting work), and a clear alternative policy for bug fixes (prefer bug-fix story for 1-2 tasks, suggest a dedicated story for 3+). This tells an agent when and how to use the tool versus creating a new 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?

With no annotations provided, the description carries the full burden, and it succeeds. It discloses that non-todo tickets produce a warning, children are reported but not deleted, dangling references need a follow-up sweep, and the deletion is recoverable from git history. This gives the agent essential behavioral expectations before invoking the tool.

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

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

The description is compact and front-loaded with the core action, then adds only high-value behavioral caveats. Every sentence earns its place, and the procedural instructions are logically ordered without excessive detail.

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

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

For a single-parameter deletion tool with an output schema, the description is complete. It covers the main operation, edge-case behavior for non-todo tickets, child handling, required follow-up cleanup, and reversibility. No critical operational context 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 0%, so the description needs to compensate for parameter meaning, but it does not explain ticket_id beyond the schema's own string type and title. The connection between 'a ticket' and ticket_id is implicit rather than explicit, leaving format, source, and linkage behavior undocumented.

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

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

The description opens with a clear verb and resource: 'Delete a ticket.' It further differentiates behavior for non-todo tickets and distinguishes itself from sibling tools by clarifying that child ticket deletion is not automatic. This leaves 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 gives explicit procedural guidance: call delete_ticket on each child to cascade, and call sweep_blocked_by after all deletions. It does not state when not to use this tool versus alternatives, but since no sibling tool performs the same deletion operation, the usage 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?

With no annotations, the description carries the behavioral disclosure burden. It does disclose useful traits: self-contained HTML, no external requests, browser-compatible, node/edge styling, and interactivity. However, it does not clarify whether the tool writes a file to disk, whether it overwrites an existing file, or whether exporting has any side effects on project data.

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 five short, information-dense sentences with no filler. It front-loads the primary purpose and then adds distinguishing characteristics and usage context. Every sentence contributes useful information.

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

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

The tool is simple and an output schema exists, so return value details are covered. However, the only parameter is left completely unexplained, and file-output behavior is ambiguous. These are real gaps for an agent deciding whether to pass output_path or rely on the default.

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

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

Schema description coverage is 0%, and the only parameter, output_path, is not mentioned anywhere in the description. The description does nothing to explain what output_path controls, what its null default means, or how it should be supplied. This is a significant gap because the description must compensate for the schema's lack of documentation.

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: 'Generate a self-contained HTML file visualising the project as an interactive graph.' It is clearly distinct from the sibling project-management tools such as create_task, list_tickets, and init_project, which do different things. The description also explains graph features, making the 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?

Provides clear usage context: 'On-demand — call when you want a snapshot.' This tells the agent when the tool is appropriate. It does not explicitly name alternatives or state when not to use it, but the sibling tools are sufficiently different that this is a minor gap.

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?

No annotations are provided, so the description must carry the safety and behavior burden. It clearly says 'Read' (non-mutating), mentions the full body, and reveals the derived blocking info. It does not detail errors or permissions, but for a read tool with an output schema, the core behavior is transparent.

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

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

Two sentences with no waste. The core action is front-loaded in the first sentence, and the second sentence adds one valuable distinguishing behavior. Every word earns its place.

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

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

For a single-ID read tool with an output schema and no annotations, the description covers the purpose, scope, and the one non-obvious behavior (blocking direction). It does not mention what happens if the ticket ID is missing or invalid, but the output schema and common read-tool semantics likely cover that. Slightly more context about how ticket_id relates to other tools could improve 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?

The schema has one required parameter, ticket_id, with 0% description coverage. The description's 'by ID' reinforces the obvious purpose of the parameter but adds no extra detail about format, source, or representation. This is acceptable for a single self-evident parameter but does not go 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 opens with 'Read one ticket by ID, with its full body' — a specific verb, resource, and scope. It also adds the unique blocking-report behavior, which immediately distinguishes it from siblings like list_tickets and update_ticket.

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 that the blocking direction is not stored on the ticket itself and that this is 'the only way to see it,' giving a clear context for when this tool is needed. It stops short of explicitly naming alternatives or stating when not to use it, so it gets 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?

With no annotations present, the description carries the full disclosure burden and performs well: 'Non-destructive and idempotent' states the safety profile, and it names exactly what side effects occur (creates primer/ store, modifies CLAUDE.md, conditionally AGENTS.md). This is precisely the kind of behavioral context annotations would otherwise provide. Minor gap: no mention of what is returned on completion, though an output schema exists.

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

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

Four sentences, zero filler. The purpose and concrete effects come first, safety follows, then the one-time ordering constraint, then the optional-parameter guidance. Every sentence carries distinct information, and the most critical scoping constraint ('before any other tool') is prominently placed.

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 project-initialization tool with no annotations and an output schema to cover return values, the description covers everything needed: what gets created or modified, idempotency/safety, the once-and-first invocation rule, and when to supply the optional parameter. 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 0%, so the description must compensate. It does explain jira_project_key's conditional purpose ('if tickets may later be exported to Jira'), which is genuinely additive beyond the schema's bare 'Jira Project Key' title. However, project_name receives no semantic treatment beyond its schema title 'Project Name', which is trivial but still undocumented at the description level. Partial compensation only.

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

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

The description opens with a specific verb and resource ('Initialise this project for primer-mcp') followed by concrete actions: 'creates the primer/ ticket store and adds the workflow section to CLAUDE.md (and AGENTS.md if it exists)'. This clearly differentiates it from all 16 siblings, which are ticket lifecycle and planning operations.

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

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

The description gives explicit usage context: 'Call this once per project, before any other tool.' It states the ordering constraint relative to every sibling tool, and the jira_project_key line adds a conditional-use guideline. It does not name specific alternatives or when-not conditions, but given that the sibling list contains only post-initialization tools, the intended usage is 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?

No annotations are provided, so the description carries the full burden. It discloses what the tool returns (goals, story coverage, actionable items table) and prescribes presentation behavior (show the full table first, add recommendation below). It does not discuss side effects, but 'List' and 'Returns' imply a read-only operation.

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

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

The description is front-loaded with the core purpose and output summary, then uses a clear numbered checklist for recommendations. It is longer than strictly necessary, but each section earns its place by guiding the agent's behavior after invoking the 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 zero-parameter listing tool with no annotations, the description is remarkably complete. It explains the output, the required presentation order, how to interpret coverage, when to recommend planning, how to prioritize urgent items, and how to handle ties.

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, so the baseline is 4. There is no parameter semantic burden for the description to carry, and it appropriately focuses on output and usage behavior instead.

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 specific verb and resource: 'List what can be acted on right now, with epic context.' It clearly differentiates this from a generic ticket listing by emphasizing epic goals, story coverage, and an actionable table. The output contents are enumerated, making the tool's purpose concrete.

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 strong context on how to use the tool's output: present the table first, then recommend next steps, and it names related tools like create_story and get_ticket for follow-up actions. It does not explicitly contrast itself with list_tickets or say when not to use it, so it falls short of full exclusion guidance.

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

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

No annotations are present, so the description carries the burden of behavioral disclosure. It does disclose output format ('one per line'), ordering ('newest work last'), and available filters. However, it does not clarify whether filters can be combined or whether status accepts specific enumerated values.

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

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

The description is two sentences long, front-loaded with the main action, and every clause earns its place. It states behavior, filters, and intended use without any 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?

The description covers ordering, output format, filter fields, and the intended pre-call use case. An output schema is present, so return-value structure is handled elsewhere. The main gaps are status value enumeration and explicit statement that filters may be combined, but overall the description is adequate for a simple optional-parameter 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?

Schema description coverage is 0%, so the description is essential. It provides acceptable values for ticket_type (epic, adr, story, task, spike) and defines parent_id semantics ('show only children of that ticket'). Status is only named without allowed values, and the phrase 'or' leaves filter combination ambiguous, but the core meaning of each parameter is conveyed.

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 tickets') and adds concrete output formatting ('one per line, newest work last'). It also states the intended role ('Use this to find an ID before calling another tool'), which distinguishes it from singular retrieval or mutation tools like get_ticket, update_ticket, or delete_ticket.

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 clear usage directive: 'Use this to find an ID before calling another tool.' It also explains the filter options, providing enough context for selecting this tool over alternatives, though it does not name sibling tools or explicitly 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?

No annotations are provided, so the description carries the full burden. It states that the tool creates an epic, but does not disclose side effects, persistence behavior, required preconditions, permissions, or what response to expect. This is a meaningful gap for a state-changing tool.

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

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

Three tight sentences that front-load the core action, then give workflow context and a useful cross-reference. Every sentence earns its place 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?

Gives a clear role, usage sequence, and relationship to record_adr while an output schema exists for return values. The main gap is not addressing whether init_project is a prerequisite, but overall the description is adequate for this planning tool.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully maps 'why the work matters' to why, 'goals' to goals, and 'how you'll know it's done' to success_criteria. However, non_goals and constraints are left unexplained, and title is only implicit.

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

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

Describes a clear action and resource: 'Create an Epic — the top-level container for a body of work.' This distinguishes it from story/task-level sibling tools and immediately clarifies its position in the planning hierarchy.

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 strong contextual guidance with 'Start here' and suggests using record_adr before creating stories. However, it does not explicitly state when not to use plan_epic or name create_story as the alternative for story-level work.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the record's contents but does not state that this creates a persistent artifact, whether it is idempotent, what side effects occur on the associated epic, or any permission/ordering constraints beyond the timing recommendation.

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, front-loaded with the core purpose, and every sentence earns its place. The first sentence defines the action and content; the second adds a valuable workflow recommendation 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?

Given the presence of an output schema and six required parameters, the description provides enough semantic coverage for the main fields and ties the tool into the broader planning workflow via the 'before creating stories' guidance. It falls just short of full completeness because it does not clarify the title/epic_id relationship or describe any behavioral constraints.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for context, decision, alternatives, and consequences ('alternatives rejected (with reasons)', 'consequences accepted'). However, it does not explicitly explain epic_id or title, though 'under an epic' implies epic_id.

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: 'Record an Architecture Decision Record under an epic.' It also enumerates the content of the ADR (context, decision, alternatives, consequences), making it clearly distinct from sibling tools like create_story or plan_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 explicitly recommends using this tool before creating stories: 'Recording decisions before creating stories is recommended.' This gives clear contextual timing for use, though it does not explicitly state when not to use the tool or name 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?

No annotations are provided, so the description carries the full burden — and it delivers. It discloses the permissive transition behavior ('Works from any status') and the unusual-transition feedback ('you'll get a note if the transition is unusual'). Minor omissions like permissions and audit logging are acceptable for a simple status change.

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

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

Three short sentences, each earning its place: purpose plus trigger, behavioral nuance, and the next lifecycle step. Front-loaded with the verb and resource, with zero 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 one-parameter tool with an output schema, everything an agent needs is present: purpose, trigger condition, prerequisite behavior, unusual-case feedback, and the next step. The output schema covers return values, so no description of those is needed.

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

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

Schema coverage is 0%, and the description adds no format or source for task_id (e.g., that it comes from create_task or list_tickets). However, task_id is a single self-explanatory string within an obvious lifecycle, so the practical harm of the missing detail is minimal.

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: 'Transition a task to in-progress.' The target state is explicit and clearly distinguishes the tool from lifecycle siblings like complete_task, verify_task, and create_task without needing to open their schemas.

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

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

Explicitly names the trigger condition: 'call this when you begin working on a task.' It also names the follow-up alternative ('After finishing, call complete_task') and removes prerequisite ambiguity with 'Works from any status.'

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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool mutates data by removing references and clarifies the trigger condition. It doesn't mention reversibility or the exact scope (whether it sweeps all stale references globally or only those related to the recent batch), but the core behavior is transparent enough for an agent to use it safely.

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 action is front-loaded, and the usage timing follows immediately. Every word earns its place.

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

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

For a zero-parameter tool with an output schema, the description is largely complete: it explains what it does and when to call it. A minor gap is whether the sweep affects only references created by the current batch or all historical stale references, but this is not critical given the simple action.

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

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

The tool takes zero parameters, and the schema has 100% coverage with an empty properties object. There is no need for parameter explanation. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than arguments.

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 ('Remove') and resource ('blocked_by references that point to tickets that no longer exist'). It clearly distinguishes this as a cleanup operation for orphaned references, which is distinct from sibling tools like delete_ticket or update_ticket.

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

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

It explicitly states when to invoke the tool: 'Call once after finishing a batch of delete_ticket calls.' This gives unambiguous temporal context and implies the intended workflow, even though it doesn't name alternative tools. No alternative is needed for such a specialized cleanup action.

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 no annotations, the description carries the full burden of behavioral disclosure. It explains partial-update semantics, the allowed status values, that blocked_by replaces the whole dependency list, validation failures for nonexistent tickets or cycles, the direction convention ('A blocks B' means setting blocked_by on B), and that body_sections replaces whole sections by heading. This is unusually thorough.

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 most important behavior ('anything left out is left alone'). Every sentence earns its place, covering replacement semantics, validation, direction, and sibling alternatives 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?

The description is nearly complete for a 5-parameter tool with no annotations and no schema descriptions. The only real gap is the unexplained external_ref parameter; everything else needed to call the tool correctly is present. Return values need not be covered since an output schema exists.

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

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

Schema description coverage is 0%, so the description must clarify parameters. It does well for status (allowed values, finished-state routing), blocked_by (replacement, validation, direction), and body_sections (replacement by heading). However, external_ref is never mentioned, leaving its semantics to inference. ticket_id is self-evident from its name.

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

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

The description states a clear verb ('Amend') and resource ('a ticket') and immediately clarifies the update model: partial amendments where unspecified fields are untouched. It also distinguishes itself from siblings by explicitly naming complete_task, verify_task, and complete_spike as the right tools for finished states.

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

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

It explicitly says to prefer complete_task, verify_task, or complete_spike when handling finished states, with the reason that they also record notes. This gives an agent a concrete decision rule for when to avoid update_ticket and pick a 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?

No annotations are provided, so the description carries the behavioral burden. It discloses the state mutation ('Sets the task to verified'), the prerequisite flexibility ('works from any status'), and the evidence requirement. It does not discuss reversibility or side effects, but core behavior is transparent.

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

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

The description is three sentences with no filler. The purpose, example, parameter guidance, and sequencing advice are all front-loaded and each sentence contributes useful information.

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

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

For a simple three-parameter state-transition tool with an output schema, the description covers purpose, evidence semantics, commit labelling, call ordering, and the resulting state. Minor omissions include reversibility and side effects, but they are not essential for correct invocation.

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

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

Schema description coverage is 0%, but the description adds meaning for commit ('short commit hash... labelled consistently') and evidence with a concrete example. task_id is left implicit, though its purpose is self-evident from the parameter name and required status.

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 ('Verify a task with evidence that the work holds') and gives a concrete example. It also states the resulting state change ('Sets the task to verified'), which clearly distinguishes it from the sibling complete_task.

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

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

It explicitly advises 'Ideally call complete_task first to capture notes, but this works from any status,' giving sequencing and an alternative. It also explains why the commit hash should be passed, though it does not enumerate exclusions or every alternative.

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