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 does disclose one real behavioral trait — the record is persisted with the project and outlives the session — but says nothing about whether this is an append-only write, whether duplicates are allowed, permissions required, or what the call returns.

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

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

Two tight sentences with zero waste; the core action and captured content come first, with the persistence rationale as supporting context.

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

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

For a five-parameter mutation with no annotations and no output schema, the description covers intent and persistence but leaves success/failure behavior and the return value unstated. Adequate to call it, not sufficient to predict what comes back.

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 80%, so the schema already documents title, reason, decision, and alternatives almost verbatim. The description restates the same what/why/alternatives framing and implies the project binding, but adds no format, length, or optionality guidance beyond the schema (projectId is not discussed at all).

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 (record) plus the resource (a design decision for a project) and enumerates the content it captures: what was chosen, why, and rejected alternatives. That is enough to separate it from list_decisions without opening a schema, though the sibling is never named.

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

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

Usage is only implied — an agent infers 'call this when a design choice is made' from the verb and the durability line. There is no explicit when-to-use, no prerequisite (e.g., project must exist), and no pointer to list_decisions for reading them back.

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 must carry the full behavioral burden, yet it only implies a write operation. It does not say whether a project link is required, whether duplicates are prevented, what happens when projectId is omitted, or what the response contains. It does state the MoSCoW vocabulary, but that duplicates the schema enum.

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

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

A single front-loaded sentence with no filler. It is appropriately sized, though its brevity reflects missing content rather than disciplined compression.

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

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

For a mutation tool with zero annotations, no output schema, and an optional linking parameter, the description is too thin. An agent cannot tell from it what the side effects are, whether a project must pre-exist, or how this differs from bulk import.

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 75%, so most parameters are already documented. The description expands the priority enum into MoSCoW terminology, but adds no meaning for title, description, or the optional projectId linking behavior, so it sits at the baseline.

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

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

The description pairs a specific verb ('Record') with a precise resource ('product requirement') and names the priority scheme. It does not explicitly distinguish itself from siblings such as update_requirement, list_requirements, or import_requirements, but the add-vs-update/list contrast is reasonably inferable.

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

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

There is no statement of when to use this tool rather than update_requirement, import_requirements, or add_user_story, and no prerequisites (e.g., whether a project must exist) are given. Usage is only implied by the verb.

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

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

With no annotations at all, the description carries the full burden of behavioral disclosure. It reveals the required text format and that acceptance criteria are mandatory, but says nothing about whether the story is attached to a project, what is returned (e.g., a new story id), permission requirements, or error behavior for a mutating create 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?

A single compact sentence that front-loads the verb and immediately gives the required format. Nothing is wasted and no filler is present.

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

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

For a 6-parameter mutation with no annotations and no output schema, the description covers the core text fields but leaves the linking parameters (projectId, requirementIds) and the return value unexplained. It is minimally sufficient but has visible gaps an agent would notice.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning by explaining how persona, goal, and benefit compose into one sentence and that acceptance criteria are part of the payload. It still says nothing about the optional projectId and requirementIds linking parameters.

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

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

The description states a specific verb and resource ("Create a user story") and even specifies the canonical sentence structure the story must take. It is clearly distinct from update_user_story, delete_user_story, and add_requirement, though it never names those siblings to reinforce the boundary.

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

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

There is no statement of when to use this tool versus add_requirement, update_user_story, or import_requirements. The agent must infer usage purely from the name and the format sentence; no prerequisites, exclusions, or alternatives are given.

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

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

With no annotations, the description carries the full burden and does disclose mode-specific behavior: strict blocks advancement and reports missing items, free advances and reports skipped items, and verification closes the project. It omits important behavioral details such as whether closure is destructive or reversible, required permissions, error conditions, and how the mode is configured.

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 compact sentences, front-loaded with the primary action and then the mode-specific outcomes. Every sentence adds relevant information without 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?

It covers the core transition logic and the special verification/closing behavior, which is useful for a state-changing tool with no annotations or output schema. However, it leaves out phase ordering, how strict/free mode is selected, destructive side effects of closure, and error cases, making it only partially complete for the complexity involved.

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% for the sole required parameter, projectId, and the description never mentions projectId, its role, or expected format. The description introduces mode concepts but those are not parameters, so it adds no meaning about the actual input.

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

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

The description states a specific verb and resource ('Move to the next phase') and explains the outcomes of advancing. It does not explicitly define what a phase is or differentiate against the sibling set_project_mode, but the core operation is clear.

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

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

The strict/free mode behavior implies when the tool will advance versus list missing items, and the verification edge case is noted. However, there is no explicit guidance on when to use advance_phase versus set_project_mode or update_project, no prerequisites, and no exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that archived projects are hidden from list_projects and that nothing is deleted, implying reversibility via unarchive. However, it omits permissions, effects on related records such as stories or requirements, and error or return behavior.

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

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

The description is three short sentences with no wasted wording. The main action is front-loaded, followed by the key visibility and non-destructive behavior.

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 low-complexity mutation, the description covers the core purpose, visibility side effect, and non-destructive nature. But with no annotations, no output schema, and zero parameter documentation, it leaves out invocation-critical details such as the default for archived and the meaning of projectId.

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% for two parameters, so the description should compensate. It does not name projectId or archived, explain that archived defaults to true, or clarify how the boolean selects archive versus unarchive; only the general action is implied.

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

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

The description states a specific verb and resource: archive or unarchive a project. It also distinguishes the operation from deletion by saying 'Nothing is deleted' and clarifies its effect on list_projects, which helps differentiate it from siblings like delete_project and update_project.

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

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

It gives clear context for use: hiding or unhiding a project without deleting it, and notes that archived projects are hidden from list_projects by default. It implies an alternative to delete_project, but does not explicitly state when not to use it or list prerequisites.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the initial lifecycle state ('discovery'), the phase-gating behavior of 'strict' (blocks advancing until each phase is complete) versus 'free' (allows advancing and reports what was skipped). It omits permissions/auth needs, name-uniqueness or failure behavior, which keeps it below 5.

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

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

Three short sentences, front-loaded with the action and the required inputs, then the mode behavior. No filler, no repetition of the schema.

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

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

For a 5-parameter creation tool with no annotations and no output schema, the description covers the parts an agent cannot infer: the starting phase, the mandatory inputs, and the gating semantics. It leaves the return value (project identifier/handle) and any naming constraints unstated, a modest gap given there is no output schema to lean on.

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 60%: goal, users and problem are already documented in the schema, but 'mode' has no schema description and 'name' none at all. The description compensates for the most important gap by explaining what strict vs free actually do, adding meaning beyond the bare enum list.

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

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

States a specific verb+resource ("Create a design project") and immediately characterizes the resulting object (starts in 'discovery' phase with required problem/users/goal), which separates it from update_project, duplicate_project and list_projects. It does not explicitly name a sibling it is not, so it stops short of a 5.

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

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

Creation intent is unambiguous, but there is no explicit when-to-use/when-not guidance against the many neighbouring tools (duplicate_project, import_requirements, update_project, set_project_mode). The mode sentence explains a parameter's effect rather than routing the agent between tools, so usage is only implied.

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

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

With no annotations at all, the description carries the full burden, and it does disclose genuinely useful post-creation state: the project starts in discovery with requirements and user stories open and linked to each other. However it says nothing about permissions, what happens on an invalid templateId, whether the result is idempotent, or what identifier comes back.

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

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

Three short sentences with the core action front-loaded and no padding. 'Adapt them afterwards with the usual tools' is slightly vague filler but still short and useful as a workflow hint.

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

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

For a mutation tool with no annotations and no output schema, the description gives good initial-state context but leaves the agent guessing about the required templateId's provenance and about what the call returns. Adequate, not complete.

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

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

Schema coverage is only 50%: 'name' is documented in the schema (including its default to the template name), but 'templateId' is completely bare in both schema and description. The description never explains that templateId should come from list_templates, so it fails to compensate for the coverage gap on the one required parameter.

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

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

States a specific verb+resource with a qualifying modifier ('from a starter template'), which meaningfully separates it from the sibling create_project. It never names create_project explicitly, but the template-based scope is clear enough for an agent to pick between them.

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

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

Usage is only implied by 'from a starter template'; there is no explicit statement of when to prefer this over create_project or duplicate_project. 'Adapt them afterwards with the usual tools' gestures at a follow-up workflow but names no concrete 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?

With no annotations at all, the description carries the full behavioral burden. It does disclose the blast radius ('one' diagram) and the indexing source, which limits accidental damage, but says nothing about irreversibility, confirmation requirements, or what happens to the underlying reference after deletion.

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

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

A single 17-word sentence that front-loads the action and adds exactly one useful clause about the index source. Nothing extraneous and nothing buried.

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

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

For a two-parameter, non-nested tool with no output schema, the description gives enough to call it correctly: the agent knows what gets deleted and how to source the index. The only real omission is an explicit note on irreversibility or permissions, which is a modest gap rather than a blocking one.

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

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

Schema description coverage is 0%, so the schema offers only types and integer bounds. The description compensates for one of the two parameters by explaining that 'index' is the position shown by list_flows, but leaves 'projectId' entirely uninterpreted beyond the implicit 'from a project'.

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

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

States a specific verb (delete), an exact resource (one saved flow diagram), and its scope (from a project, identified by the index from list_flows). An agent can distinguish this from sibling deletions like delete_project or delete_requirement without opening any schema.

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

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

The phrase 'by the index shown by list_flows' establishes the prerequisite that an agent must call list_flows first to obtain a valid index, which is genuinely actionable context. It lacks explicit when-not-to-use guidance or a safety caveat about irreversibility, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses permanent deletion, cascade effects on requirements and user stories, irreversibility, the confirm requirement, and that Jira issues are untouched. It stops short of covering permissions or error behavior, but the core destructive semantics are clear.

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 are front-loaded with the most important fact—permanent deletion—and each sentence adds distinct value: cascade scope, confirm requirement, irreversibility, and Jira exclusion.

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

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

For a two-parameter destructive tool with no annotations and no output schema, the description covers the essential behavior: what is deleted, what is not deleted, the confirmation gate, and irreversibility. Only minor operational details such as permissions or response behavior are missing.

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

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

Schema coverage is 50%, with confirm already described in the schema and projectId undocumented. The description reinforces the confirm requirement but adds no meaning for projectId beyond what its name implies.

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

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

The description uses a specific verb and resource: 'Permanently delete a project', and clarifies the cascade scope by naming requirements and user stories. It does not explicitly distinguish itself from the sibling tool archive_project, which is the main omission.

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

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

It states the key prerequisite that confirm must be true and warns that the action cannot be undone. However, it never explicitly says when to use this instead of archive_project or other alternatives, so the usage guidance is only implied.

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

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

With no annotations, the description must carry the behavioral burden. It usefully discloses one important side effect: removal from user stories' requirementIds. However, it omits critical details for a destructive operation, such as whether deletion is permanent, permission requirements, error behavior, and return value.

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 second sentence earns its place by disclosing a non-obvious cascade effect.

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 a destructive operation with no annotations, no output schema, and a parameter with 0% description coverage, the description is incomplete. It should cover permanence, permissions, and what happens on failure or when the requirement is in use.

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 one parameter ('id') with 0% schema description coverage. The description does not explain what the id refers to or its expected format, adding no meaning beyond the bare schema. Since coverage is low, the description should compensate but does not.

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

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

The description states a specific verb and resource ('Delete a requirement'), making the tool's core action unambiguous. It does not explicitly differentiate from siblings like update_requirement or delete_user_story, but the resource name makes the distinction clear enough.

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 no guidance on when to use this tool versus alternatives (e.g., archiving, updating status) or when not to use it. It implies deletion but provides no context about prerequisites, permissions, or irreversibility.

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 disclosure burden, and it discloses nothing: no statement about permanence, reversibility, cascading effects (e.g., related requirements or criteria), or required permissions. For an irreversible delete operation, this is a critical gap.

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

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

The single short sentence is technically waste-free, but it is under-specified rather than concise; there is nothing front-loaded because there is nothing to front-load.

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?

A destructive, one-required-parameter tool with no annotations and no output schema needs the description to supply confirmation behavior, effects, and error semantics. All of those are absent, leaving an agent unable to call this safely or correctly.

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

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

The single required parameter 'id' has 0% schema description coverage, and the description says nothing about it — not its type, whether it is the story ID or a project-scoped identifier, or what happens if it is invalid. The description entirely fails to compensate for the coverage gap.

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 is a verbatim restatement of the tool name: 'Delete a user story' adds no scope, target type, or effect beyond what the name already conveys. It does not distinguish this from siblings like update_user_story or list_stories, nor does it clarify which 'user story' resource is deleted in the context of the project-oriented siblings.

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

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

There is no guidance on when to use this versus update_user_story, delete_requirement, or delete_flow, and no prerequisites or cautions about a destructive operation. An agent has nothing to reason about beyond the word 'delete'.

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 and does so well: it discloses that requirements and user stories are copied as open items, and that statuses and RICE scores are not copied. It does not mention permissions, source-project impact, or return value, but the key copy/exclusion behavior is explicit.

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-loads the core behavior, and uses the second sentence for useful context and exclusion details. Every sentence earns its place.

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

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

For a simple two-parameter duplication tool with no output schema and no annotations, the description covers purpose, copy behavior, exclusions, and a representative use case. The main remaining gap is parameter-level detail, but the overall context is sufficient for an agent to select and invoke it.

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 for parameter meaning. It implies that the existing project is the source (projectId) and the new project is the destination (name), but it never names the parameters or explains constraints such as the minimum name length. For two self-explanatory parameters this is minimally adequate, but not fully compensatory.

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

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

The description states a specific verb and resource: creating a new project from an existing one and copying requirements and user stories. It distinguishes itself from a blank create_project by emphasizing duplication from an existing project, though it does not explicitly name that sibling.

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

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

It gives a clear usage context: as a template for a new client or product. It does not explicitly state when not to use it or name create_project as the alternative for starting from scratch, but the intended scenario 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 full disclosure burden, yet it never says whether the export is returned as text, as a path, or written to disk — the destructive/read-only and file-writing profile is left entirely to the schema's `save` field. It also omits size limits, permissions, and ordering guarantees beyond "most important first".

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

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

A single front-loaded sentence with the resource and formats named first and content detail appended after the colon. No filler, though the embedded parenthetical makes it slightly dense to parse.

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

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

For a three-parameter tool with no annotations and no output schema, the description leaves the most consequential question unanswered: what does the caller receive back, and does `save` change that. Compared to what an agent needs to invoke an export correctly, this is thin.

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

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

Schema coverage is only 33% (only `save` is documented), so the description must compensate; it does partially by naming both formats and the ordering semantics, which maps to the `format` enum and clarifies output content. `projectId` is left unexplained, though its meaning is self-evident from the tool 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?

States a specific verb and resource ("Export a project backlog") plus the two output formats and the content included (requirements, user stories). This clearly separates it from siblings like export_dashboard or project_summary, though it never names an alternative explicitly.

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

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

There is no statement of when to use this versus project_summary, search_items, or the Jira push/pull tools. Usage is only implied by the verb "Export" — an agent must infer the scenario itself.

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: it does disclose the write target ('data/exports/dashboard.html') and that the output is read-only HTML, which is useful. It omits whether an existing file is overwritten, what permissions or project scope are required, and what the tool returns on success or failure.

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

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

A single dense sentence that front-loads the verb and destination before the content list, with no filler. The colon-separated content list is efficient, though the final 'Open the file in a browser' clause would be better placed as explicit follow-up guidance.

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

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

No output schema and no annotations, so the description must stand alone; it does cover destination and content, which is the core. It still leaves out overwrite semantics, the role of the optional projectId, and the distinction from the open_dashboard sibling, which are the gaps an agent would hit in practice.

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

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

There is one optional parameter (projectId) with 100% schema description coverage, so the schema already explains it and the baseline is 3. However, the description never mentions projectId at all, so it adds no meaning about how scoping by project changes the exported content or what happens when it is omitted.

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

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

Specific verb plus resource: writes a read-only HTML dashboard to a named path and enumerates the sections it contains (phases, gaps, musts covered by stories, RICE scores, flow diagrams). It distinguishes itself from export_backlog by listing dashboard-specific content, though the trailing 'Open the file in a browser' instruction blurs the line with the open_dashboard sibling.

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

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

There is no statement of when to call this versus open_dashboard, export_backlog, or project_summary. The only guidance is a post-step instruction ('Open the file in a browser'), which reads as an action instruction rather than a selection criterion, and it actually increases ambiguity about whether this tool opens the file or just writes 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 supplied, so the description carries the full behavioral burden. 'Show' plus the enumerated fields (phase, missing-to-advance, linked items) make it clear that this is a read that assembles related state, which is useful context. However, it says nothing about behavior for an unknown or archived projectId, permissions, or how expensive/large the response can be.

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

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

A single efficient sentence with the core purpose front-loaded. Only 'what is missing to advance' is slightly vague and could be tightened into concrete field naming.

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

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

For a one-parameter read tool with no output schema, the description partially compensates by naming the returned fields. It still leaves the required identifier semantics and failure modes undocumented, so it is adequate but not complete.

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

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

Schema description coverage is 0% and the description never mentions the single parameter, projectId. The agent must infer from the name alone that it identifies the project, and the schema gives no format or provenance hints for the integer 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 gives a specific verb (Show) and resource (a project) and enumerates what is returned: current phase, missing-to-advance items, and linked items. That makes it distinguishable from list_projects or update_project, though it never contrasts itself with project_summary, which is the most plausible overlapping sibling.

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

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

Usage is only implied by the phrase 'Show a project's status'. There is no statement of when to prefer this over project_summary or list_projects, and no prerequisites such as needing a valid projectId. An agent must infer the call context.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that story-to-requirement links are not restored and specifies required row fields, but it does not say whether imports are additive or overwriting, how duplicates are handled, whether the operation is atomic, or what permissions are needed.

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 front-loaded sentences with no wasted words. It communicates the core action, format source, required row contents, and an important limitation efficiently.

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

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

For a mutation import tool with no annotations and no output schema, the description covers input format and a key data-loss caveat but omits important behavioral details such as overwrite/duplicate behavior, error handling, and atomicity. It is adequate but incomplete for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains the csv parameter's row types, required fields, and delimiter; projectId is not described, though its purpose is self-evident from the 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 names a specific verb and resources: importing requirements and user stories from CSV text, explicitly tied to the export_backlog format. This makes it clearly distinct from siblings like export_backlog and the single-item add 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?

It clearly states the intended input source and format, implying when to use it instead of adding items individually. However, it does not explicitly name alternatives or state exclusions, such as using add_requirement/add_user_story for single items.

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. It usefully discloses ordering ('oldest first'), but says nothing about pagination, empty results, permissions, or whether archived projects are included.

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

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

A single front-loaded sentence with no filler; the ordering detail earns its place. Slightly terse for a tool with an undocumented parameter.

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

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

For a simple one-parameter read tool this is close, but with no output schema the description should indicate the shape of returned decisions and whether results are paginated or limited.

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 should compensate, yet it only weakly ties the sole projectId parameter to 'for a project'. No ID format, validation, or behavior for invalid/foreign project IDs is given.

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

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

States a specific verb and resource (list design decisions) plus scope (for a project), which is distinguishable from the sibling add_decision. It doesn't explicitly name siblings, but the read-vs-write distinction is clear from the verb.

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?

'List ... for a project' implies a read of existing decisions scoped by projectId, and the add_decision sibling covers the write path. No explicit when-to-use, when-not-to-use, or alternative is named, so guidance is only implied.

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

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

No annotations are provided, so the description carries the burden itself. It implies a read-only listing and confirms the return includes an index per diagram, but it says nothing about pagination, ordering, empty-project behavior, or access permissions.

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

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

Two short sentences, front-loaded, with the index semantics stated immediately after the action. No filler.

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

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

For a single-parameter read tool with no output schema, the description covers the action and the key return concept (index). It could say a bit more about what each listed entry contains, but it is adequate to invoke the tool correctly.

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

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

There is one required parameter (projectId) with 0% schema description coverage, so the description must compensate. Phrasing it as 'saved in a project' does tie the parameter to a project, but it adds no detail on ID format or source.

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

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

The description gives a specific verb and resource ('List the flow diagrams saved in a project'), which clearly distinguishes it from siblings like delete_flow, map_user_flow and list_projects. It doesn't explicitly name or contrast a sibling, which keeps it at 4.

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

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

'Use the index to refer to a diagram' implies the intended follow-up workflow, so usage is inferable. However there is no explicit guidance on when to pick this over alternatives (e.g. list_projects or map_user_flow) and no stated prerequisites.

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

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

With no annotations provided, the description carries the full behavioral burden. 'List' implies a read-only operation and the returned fields are disclosed, but key behavior such as default filtering of closed/archived projects, ordering, pagination, and permission requirements is not described.

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

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

The description is two short sentences with no filler, and the core purpose is front-loaded before the usage hint.

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 list tool with rich schema descriptions and no output schema, the description is mostly complete: it names the returned fields and the primary use case. It could mention the closed/archived filtering defaults, but the schema covers those details.

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

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

Schema description coverage is 100%, so both optional parameters are already documented in the schema. The description adds no parameter-specific guidance beyond the schema baseline.

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

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

The description states a specific verb and resource ('List projects') and names the returned fields ('id, name, phase and status'). It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like get_project or search_items.

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 sentence 'Use it to find a projectId' gives a clear intended use case. It does not name alternatives or exclusions, but the context for when to call it is explicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the sort order ('Most important first'), which is useful, but does not explicitly state read-only behavior, pagination, return shape, or permission requirements for a list operation.

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

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

Two compact sentences with no wasted words. The tool's action is front-loaded, followed immediately by optional filters and ordering.

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 list tool with no annotations and no output schema, the description covers the basic action, filters, and sort order. However, it leaves out return behavior, pagination, and explicit read-only reassurance, which would be helpful given the lack of structured annotations.

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

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

Schema description coverage is low at 33%, so the description should compensate. It names all three parameters as optional filters, which adds semantic value beyond the raw schema, but it does not explain allowed values, defaults, or the distinction between project ID and project name beyond what the schema already implies.

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

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

States a specific verb and resource ('List requirements') plus optional filter fields and sort order. It clearly identifies the resource, but does not explicitly differentiate this from sibling tools such as search_items or list_stories.

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

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

The phrase 'optionally filtered by priority, status and project' implies the main usage scenario, but there is no explicit guidance on when to use this versus search_items or other list tools, nor any exclusions or prerequisites.

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

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

With no annotations, the description carries the burden; it usefully implies a read-only listing and discloses which fields come back. However, it says nothing about pagination, ordering, default scope when projectId is omitted, or permissions, which matter for a list tool.

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

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

Two sentences, no filler, with the core purpose front-loaded and the practical motivation (finding a storyId) appended. Every clause conveys 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?

Because there is no output schema, naming the returned fields is genuinely valuable and covers the main gap. Remaining omissions are pagination and default cross-project behavior, which are minor for a simple listing 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 the single projectId parameter is fully documented, so baseline is 3. The description adds that filtering by project is optional, reinforcing the schema's non-required status and clarifying it narrows rather than requires a project.

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

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

States a specific verb ('List') and resource ('user stories'), plus the optional project scope and the fields returned (ids, criteria state, Jira key). This distinguishes it from siblings like add_user_story, update_user_story, and list_requirements without the agent needing to open any schema.

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

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

"Use it to find a storyId" gives a concrete downstream purpose, and "optionally for one project" clarifies the scope. It stops short of naming an alternative tool or stating when not to use it, so it falls just below the explicit when/when-not bar.

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 burden. 'List' plus a fixed enumeration of two known entries effectively signals a trivial, safe, read-only, non-paginated call, but the description never says so outright, nor does it state whether the set is fixed or could grow.

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

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

Two short sentences, zero waste. The content of the listing is front-loaded before the routing hint, which is exactly the right ordering.

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

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

With no output schema and no annotations, the description compensates by naming the concrete return values the agent will see. Combined with the named follow-up tool, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no param-level gaps exist because no params exist.

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

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

States a specific verb and resource ('List the starter project templates') and goes further by enumerating the actual contents (marketplace MVP, customer self-service portal). An agent can distinguish this from list_projects or list_stories purely from the description.

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

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

Explicitly names the follow-up tool ('Use one with create_project_from_template'), which is the only meaningful usage decision for a zero-parameter lister. It stops short of saying when NOT to call it, but there is no plausible alternative it could be confused with.

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 behavioral burden. It discloses that providing projectId saves the diagram to the project, which is a useful side-effect hint. However, it omits details on permissions, whether saving overwrites or creates, and what the return value is (e.g., Mermaid text vs. saved object), leaving significant gaps.

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

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

Three sentences with no wasted words, front-loading the core purpose. Could be slightly more structured, but the information is efficiently delivered.

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 nested step objects, no output schema, and an optional save behavior, the description should clarify what is returned (e.g., Mermaid string) and what happens when projectId is omitted. It also doesn't address error conditions or the required 'name' parameter's role, leaving the agent with critical unknowns.

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 only 33%, and the description does not compensate: it never explains the 'name' parameter, does not describe the top-level 'steps' shape (array of objects), and only partially clarifies decision edges which are already documented in the schema. 'ends' and 'next' are not mentioned in the 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?

States a specific verb (Generate) and resource (Mermaid flowchart) from a list of steps, clearly distinguishing it from sibling tools like list_flows or delete_flow. An agent can immediately understand what the tool produces.

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 usage for generating flowcharts from steps, and mentions the optional projectId for saving, but provides no explicit when-to-use vs alternatives or conditions for choosing this over other flow-related tools. Guidance is only implicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses read-only behavior, local-only binding to 127.0.0.1, lifecycle tied to Yeti running, and self-refresh. It does not address repeated invocation behavior (e.g., whether calling twice starts multiple servers or reuses one), leaving a minor operational gap.

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

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

The description is three compact sentences, front-loads the action and return value, and uses the remaining space for operationally relevant details (read-only, local-only, auto-refresh). Every sentence earns its place.

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

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

For a zero-parameter tool with no output schema, the description supplies what the agent needs: the returned address format, read-only safety, local scope, lifespan, and dashboard contents. Nothing important for correct invocation is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Baseline 4 applies; the description appropriately focuses on return value and runtime behavior instead of inventing parameters.

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

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

States a specific verb and resource ('Start the local, read-only Yeti dashboard') and adds scope (local-only, live while Yeti runs), which clearly distinguishes it from the sibling export_dashboard. An agent can identify the action without opening the schema.

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

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

Usage is implied by 'local, read-only' and 'runs on this computer only, while Yeti runs', which suggests a live local inspection workflow. However, it does not explicitly say when to choose this over export_dashboard or when not to use it, so the agent must infer the boundary.

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

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

With no annotations, the description carries the full burden, and it does disclose the key trait that this tool can mutate state when projectId is supplied. However it leaves the persistence semantics unexplained: whether saved items are appended or overwrite existing project items, whether validation failures on the numeric ranges abort the whole batch, and whether the save is reversible. Those are material gaps for a tool with a write path.

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

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

Two sentences, front-loaded with the core computation, with the conditional side effect second. Every clause earns its place and nothing is padded.

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 compute tool with no output schema and no annotations, the description should say what comes back — e.g. a sorted array with computed scores, and whether saved items return IDs. It also omits tie-breaking and handling of invalid inputs. Adequate to call the tool, but not complete.

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

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

Schema coverage is only 50%, so the description needs to compensate, and it does meaningfully: it explains that projectId is not a filter but a persistence trigger, and the formula clarifies how reach/impact/confidence/effort combine into the output. It adds little about the item shape itself (names, ordering of results), but the numeric field meanings are already documented 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?

States a specific verb and resource ('Compute RICE scores ... for a list of ideas and sort them') and even supplies the formula (Reach × Impact × Confidence ÷ Effort), so the operation is unambiguous. The conditional side effect ('With projectId, saves the result to the project') further pins down what the call does; no sibling tool does scoring, so confusion is unlikely.

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 sentence 'With projectId, saves the result to the project' tells the agent about a mode switch, but it is phrased as behavior rather than guidance — it never says when to persist vs. compute-only, nor what prerequisites or consequences follow from saving. Usage is implied rather than stated, and no alternatives are named.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Summarise' implies a read-only aggregate and the enumerated contents effectively describe what is computed (must-coverage, RICE leader, missing items), which is useful. However, it says nothing about whether it mutates state, cost/latency on large projects, or how empty/partial projects are handled.

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

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

A single front-loaded sentence with the verb and scope first, followed by a compact enumeration. The list of summary components is dense but each item conveys real information about the returned payload, so little is wasted.

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

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

With no output schema, the description must explain the return value, and it does so reasonably by enumerating the summary sections. It is still incomplete on parameter provenance, behavior for projects with no requirements/stories, and whether the summary is read-only.

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 single required parameter projectId has no description in either the schema or the description text. The name is fairly self-evident, but the description does not say where to obtain a valid id (e.g. list_projects) or what an invalid id does, so it fails to compensate for the coverage gap.

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

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

The description opens with a specific verb+resource ('Summarise a project's progress') and then enumerates the exact contents of the summary (requirements by priority/status, story coverage of musts, acceptance criteria done, RICE leader, Jira links, gaps to close). This clearly separates it from CRUD siblings like get_project or list_requirements. It stops short of naming those siblings explicitly, so it is a 4 rather than a 5.

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

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

Usage is only implied: an agent can infer this is the tool for a progress/health overview, but the description never says when to prefer it over get_project, export_dashboard, or export_backlog, and gives no preconditions (e.g. project must exist, may be empty). No when-not-to-use guidance is present.

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 load and does well: it discloses the safe-by-default dryRun preview, the idempotency-ish skip of already-sent items, and the mutating effect of update: true. It stops short of stating required permissions, failure behavior, or whether already-linked items can be duplicated.

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

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

Four short sentences, front-loaded with the core behavior, then edge semantics (skip, update, dryRun), then the prerequisite. No filler and nothing important buried.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers what gets created, what is skipped, how to preview, how to refresh, and the prerequisite. The remaining gap (return value shape) is implied by 'lists what would be sent' and is minor.

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

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

Schema coverage is only 50% (dryRun and projectId are undocumented in the schema), and the description compensates by explaining dryRun's default and effect ('only lists what would be sent') and update's meaning. limit and projectId remain explained only by name/schema; the description adds no syntax or scoping detail for projectId.

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 (create) plus the exact resource mapping: one Task per requirement, one Story per user story. That is far more precise than the name alone. It does not, however, differentiate itself from the sibling sync_tracker, which an agent may see as overlapping.

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 concrete operating guidance: items already sent are skipped, update: true refreshes linked items, dryRun only previews, and the tracker must be set via set_project_tracker first. Missing only an explicit statement of when to prefer sync_tracker or re-run behavior after configuration changes.

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 does disclose two useful behaviors: matching is case-insensitive and the scope spans requirements and user stories. It does not disclose result limits, pagination, ordering, or whether matching is substring or token-based, which are significant gaps for a search tool with zero annotation coverage.

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

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

Two short sentences, front-loaded with the core action and scope, with the optional filter stated second. Nothing is redundant.

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

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

For a 2-parameter read search with no output schema, the description covers the essentials but omits what results look like, how many are returned, and matching semantics. An agent could call it, but with uncertainty about expectations.

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 50% and the schema's projectId description is misleading ('link this item to'), while the tool description correctly reinterprets it as a project filter — a genuine value add. The query parameter's case-insensitive behavior is also clarified, but minimum length and matching semantics are left to the schema or unstated.

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

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

States a specific verb (search) and resource (requirements and user stories) plus the matching mode (case-insensitive text). It is clearly distinguishable from list_requirements and list_stories because it is text-driven rather than enumeration, though it does not name those siblings.

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

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

The phrase 'optionally limit to one project' implies when to supply projectId, and the search framing implies use over listing when a text query exists. However, it never explicitly contrasts with list_requirements/list_stories or states 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?

With no annotations, the description carries the full behavioral burden for a write operation. Beyond 'mark done/not done' it says nothing about permissions, whether the change is reversible, out-of-range index behavior, or idempotency. The 0-based note is the only added behavioral detail.

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

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

Two tight sentences with no filler; the core action is front-loaded and the essential index clarification follows. Both sentences earn their place.

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

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

For a simple three-param setter with no output schema, purpose plus the index semantics cover the core, but as an unannotated mutation it omits error/permission behavior and success outcome, leaving real gaps.

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

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

Schema coverage is 0%, so the description must compensate. It does clarify the non-obvious 'index' parameter (0-based, ordered by the criteria list), and 'done'/'storyId' are self-evident, but it adds nothing to disambiguate storyId or note constraints like the existing min/max bounds.

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 ('Mark one acceptance criterion of a user story as done or not done'), which is instantly distinguishable from update_user_story or set_requirement_status by resource. It does not explicitly name or contrast with the similar set_requirement_status sibling, so it stops short of a 5.

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

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

No guidance on when to prefer this over directly editing the story, no prerequisites (e.g., the criterion must already exist, storyId must be valid), and no mention of the analogous requirement-status sibling. Usage is implied by the name only.

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 bears full behavioral disclosure. It usefully discloses the delayed-effect rule ('Applies from the next phase change'), which is real added context, but says nothing about permissions, reversibility, or what happens to in-flight work under the new mode.

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

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

Two sentences, zero filler, and the timing caveat is placed second where it belongs. Nothing extraneous.

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 setter with no output schema, the core is covered, but the missing definition of the modes themselves and absent annotation coverage leave an agent unable to predict the tool's effect. Adequate but with a clear gap.

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

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

Schema description coverage is 0%, so the description must compensate. It conveys the enum values for mode but never explains what 'strict' vs 'free' actually change, and projectId is left entirely to the schema. 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?

States a specific verb and resource ('Change a project's mode') and enumerates the two valid modes, which separates it from generic siblings like update_project or advance_phase. It stops short of naming those siblings explicitly.

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

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

Usage is implied by the description of what the tool alters, but there is no guidance on when to prefer this over update_project or when not to call it. No prerequisites or alternatives 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?

With no annotations, the description carries the full burden. It usefully discloses the one-shot/immutable-after-send semantics, but says nothing about credential or authorization requirements for Jira/GitHub, what error occurs when the binding is rejected, or whether any remote state is created.

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 doing distinct work: capability, timing requirement with examples, and the immutability constraint. The binding verb leads, so nothing important is buried.

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

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

For a 3-param mutation with no annotations and no output schema, the description covers purpose, timing and the hard constraint well. Remaining gaps (auth prerequisites, return/confirmation behavior) are minor but real given the zero annotation coverage.

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

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

Schema coverage is only 33% (only `target` is documented), so the description must compensate — and it does: it names the enum values for `kind` and restates the accepted formats ('Jira project key, e.g. PROJ', 'owner/repo'). Only `projectId` is left implicit by 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?

Specific verb+resource: 'Bind a project to its work tracker' with the two supported kinds (jira/github) enumerated in parentheses. An agent can tell this configures tracker integration, but the description doesn't explicitly distinguish it from sibling tools like push_to_tracker or sync_tracker.

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?

'Set it once, before sending anything' gives a clear timing condition, and 'A project with items already sent cannot change tracker' gives an explicit exclusion. It stops short of naming the related sibling operations (push_to_tracker, sync_tracker) that depend on this setup.

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 for a mutation tool. It reveals the binary state model but says nothing about permissions, idempotency, side effects, or what the response contains.

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

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

A single front-loaded sentence with no filler. It is efficient, though the terseness comes at the cost of the detail noted elsewhere.

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

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

With no annotations, no output schema, and 0% parameter documentation, the description is too thin for a write tool. It does not say where status changes surface, whether the change is reversible, or how this differs from the closely named siblings.

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 description does not compensate: 'id' is never explained (requirement id? integer?) and the 'status' values named are already given by the schema enum. An agent learns almost nothing about the parameters beyond the shape of the call.

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 ('Mark a requirement') plus the resulting states ('open or done'), so the operation is unambiguous. It does not differentiate itself from the sibling set_criterion_status or update_requirement, which could plausibly also affect status-like fields.

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

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

There is no explicit guidance on when to pick this over update_requirement (which may also set status) or set_criterion_status. The only usage signal is implied by the verb 'mark', leaving the agent to infer the alternative.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that the tracker side is read-only while Yeti item statuses are mutated, but it does not cover permissions, idempotency, overwrite behavior, or what happens when items are unlinked.

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 compact sentences with the core action front-loaded. It avoids waste, though the phrase 'mark them done or open' could be slightly more precise about the status mapping.

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 sync tool with no annotations or output schema, the description covers the essential action and the external read-only guarantee. However, it lacks return behavior, error conditions, and prerequisites that would help an agent invoke it confidently.

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 0% description coverage for the single required projectId parameter. The description only implies that a project is involved and adds no details about the parameter's meaning, expected identifier source, or constraints beyond the schema type.

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 operation: read linked tracker item statuses and mark those items done or open in Yeti. It is clear enough to distinguish as a tracker-to-Yeti sync, though it does not explicitly differentiate itself from siblings such as push_to_tracker or set_project_tracker.

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 gives no explicit guidance on when to use it versus alternatives like push_to_tracker or set_project_tracker. It also omits prerequisites such as whether the project must already have a linked tracker.

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 behavioral burden. It usefully discloses partial-update semantics, but it does not mention permissions, reversibility, validation failures, or what happens if projectId does not exist. This is meaningful but incomplete behavioral context for a mutation tool.

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

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

The description is two short sentences with no wasted language. The action and partial-update rule are front-loaded and easy to parse.

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

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

For a project-mutation tool with no annotations, no output schema, and 0% schema parameter descriptions, the definition is too thin. It leaves the required projectId undocumented and does not explain permissions, side effects, or return behavior.

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

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

Schema description coverage is 0%, so the description must compensate for all five parameters. It names four optional fields, but those names are already present in the schema, and it omits the required projectId entirely while providing no format or meaning for values such as 'users'.

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

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

The description states a specific verb and resource: 'Change a project's name, problem, users or goal.' It is clear this is a project mutation tool rather than a create, delete, or read tool, though it does not explicitly differentiate from nearby siblings such as archive_project or set_project_mode.

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 says 'Only the fields you pass are changed,' which clarifies partial-update behavior, but it gives no guidance on when to use this tool versus create_project, archive_project, set_project_mode, or other project-related siblings. Prerequisites such as requiring an existing project are also unstated.

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 behavioral burden. It does disclose meaningful patch semantics ('only the fields you pass are changed'), which tells the agent omitted fields are preserved. It says nothing about permissions, whether the requirement must pre-exist, or what happens on an unknown id.

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

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

Two tight sentences with no filler; the mutation scope is front-loaded and the partial-update caveat immediately follows. Nothing could be removed without losing information.

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

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

For a 4-parameter mutation tool with no annotations, no output schema and 0% schema coverage, the description covers intent and patch behavior but leaves error handling, permissions and return values unexplained. Adequate to call correctly, not adequate to anticipate outcomes.

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 and it does partially by enumerating the mutable fields (title, description, priority) and implying id is the target. It omits constraints the schema encodes but doesn't explain, such as title's 3-character minimum and the must/should/could/wont enum, and never states that id is required.

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

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

Specific verb ('Change') plus resource ('a requirement') plus the exact editable fields (title, description, priority), which separates it from set_requirement_status and update_user_story. It stops short of naming those siblings explicitly, so an agent still has to infer the boundary.

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

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

There is no when-to-use or when-not-to-use guidance and no reference to siblings like set_requirement_status or delete_requirement. 'Only the fields you pass are changed' describes update semantics rather than selection criteria, so routing must be inferred from the name alone.

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

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

With no annotations, the description carries the full burden and does disclose the critical side effect that rewriting acceptance criteria resets their done state — exactly the kind of destructive consequence an agent must know before calling. It still lacks permission/auth requirements, behavior on invalid requirementIds, and whether fields can be cleared.

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, zero filler, with the patch semantics and the dangerous side effect surfaced immediately after the scope statement. Every sentence earns its place.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers the essentials: scope, patch semantics, and the one destructive side effect. Remaining gaps (error behavior, clearing fields, relationship replacement semantics for requirementIds) are minor but real.

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, and it does map five of the six parameters (persona, goal, benefit, requirementIds as 'linked requirements', acceptanceCriteria) to plain-language meaning. It adds nothing about the required id or the minItems=1 constraint on acceptanceCriteria, so it is helpful but not complete.

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

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

States a specific verb and resource ("Change a user story's") and enumerates the mutable fields, so an agent knows exactly which entity is affected. It implicitly separates itself from sibling tools like add_user_story and update_requirement by naming 'user story' and the story-specific fields (persona, goal, benefit, acceptance criteria). Explicit sibling routing is absent, keeping it just short of a 5.

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

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

"Only the fields you pass change" is a genuinely useful usage rule for a partial-update tool and tells the agent it need not resend unchanged values. However there is no guidance on when to use this versus set_criterion_status or update_requirement, and no prerequisites are stated.

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