Stride — AI software delivery platform

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so the description is not carrying the safety burden. It still adds genuine value by spelling out the access consequences, the default role, and the role-change-on-rerun behavior. It omits who is permitted to grant OWNER (privilege escalation concerns), which would matter for a permission-granting tool.

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

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

Three sentences, each front-loaded with its most decision-relevant fact: the action and role set first, the practical meaning second, the idempotency contract last. No filler 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 three-parameter mutation with full schema coverage and annotations covering safety and idempotency, the description supplies what the structured fields cannot: why the tool exists and what it unlocks. Only the return value / error cases (unknown member, insufficient permission) are unaddressed, and there is no output schema to defer to.

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

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

Schema description coverage is 100% and already documents projectId, member (UUID or email), and the role enum with its EDITOR default. The description's restatement of the role values and default duplicates the schema rather than adding semantics. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb (give access / add member), the resource (Stride project), and the scope of the grant (role: OWNER/EDITOR/VIEWER with EDITOR default). It also explains the concrete effect — opening the project, being assigned work, being @-mentioned — which distinguishes it from the many story/document siblings.

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

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

Gives clear context for when this tool is needed (projects are invite-only by default, so this is the mechanism that grants entry) and an explicit idempotency rule covering the re-invocation case. It does not name the neighboring alternatives stride.update_project_member_role or stride.remove_project_member, which is a real gap given how close the former is.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, so the safety bar is lower. The description still adds real value by stating the additive semantics — existing content is preserved and new content goes at the end — which is the key differentiator from a full rewrite. It does not warn that repeated calls will duplicate content or what happens if documentId is unknown.

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 the mutation and its scope front-loaded, followed by required inputs and a concrete use case. 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 two-parameter write tool with full schema coverage and safety annotations, this covers what an agent needs to select and call it. The only gap is return behavior — no output schema and no statement of what comes back or whether the appended content is echoed.

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

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

Schema description coverage is 100%, with both parameters documented including the 200k maxLength, so the baseline is 3. The description only restates the required parameter names, adding no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Append markdown to the END of an existing Library document') and pins the scope with 'END' plus 'keeping its current content'. This cleanly distinguishes it from siblings like update_document, create_document, and get_document.

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

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

Gives a concrete usage trigger: adding a section such as action items or a dated entry 'without rewriting the whole doc'. That implicitly routes the agent away from update_document, but it never names the alternative explicitly or states when not to use this tool.

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

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

Goes well past the annotations: discloses the conflict guard (rejection when a human edited the story after the agent's last read), names the conflict class implicitly, states that force overwrites a human's newer edit, and that the override is audit-logged. This is exactly the kind of risk context an agent needs before mutating shared state and that annotations alone cannot convey.

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

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

Four tight sentences, front-loaded with the action then the identifier guidance, then the risk, then the alternative. Minor redundancy with the storyId/assigneeId schema text (ticket key example repeats verbatim), but no wasted sentences.

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

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

For a non-destructive, idempotent mutation with only three parameters and no output schema, the description covers invocation, both modes, the conflict/override path, and the sibling alternative. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100% and already documents storyId formats, assigneeId null semantics, the bot-user exclusion, and the force/audit-log caveat. The description restates the same contract rather than adding format or constraint detail beyond it, so the baseline 3 applies.

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

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

States a specific verb pair (assign/unassign) against a specific resource (story), gives the two accepted identifiers, and explicitly routes broader edits to stride.update_story. An agent can distinguish this from update_story and bulk_update_stories without opening a schema.

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

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

Covers both directions of use (assigneeId to assign, null to clear), the prerequisite for the force path (human's explicit approval), and names the sibling to use for broader field edits. When-to-use and when-not-to-use are both 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?

Beyond the destructive/idempotent annotations, it discloses the conflict model (per-row conflict check, human-edited rows skipped and recorded in SyncConflict), the audit-logged override path, and the crucial failure semantics: an unresolvable ticket key rejects the whole call before any write, only parseable-but-dead ids land in notFound. This is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the core action and scoped fields before the edge cases. The later sentences are dense, run-on, and dash-laden (the notFound/soft-error sentence especially), which slightly impedes scanning, but nothing is 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 destructive, nested-parameter batch mutation with no output schema, the description covers input formats, conflict handling, force semantics, partial-success vs. rejection behavior, and return arrays. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 67%, and the description closes the remaining gaps rather than repeating it: labels {mode, labels[]} semantics, the project-specificity constraint on status column names, the mixed ticket-key/UUID allowance for storyIds, and the all-or-nothing behavior tied to key resolution. It adds real meaning beyond the schema's per-field text.

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

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

Opens with a specific verb+resource+scope: 'Update up to 50 stories in one call', which immediately separates it from stride.update_story (single) and stride.update_story_status. It then enumerates exactly which fields are batch-updatable, so the agent knows the tool's surface 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?

Gives explicit conditions rather than vague context: status may be a category or a column name from stride.list_workflow_stages, and a column name requires a single-project batch. It also states when to pass force (only with explicit human approval) and advises verifying keys with stride.get_story first when unsure — genuine routing guidance, not just a restatement.

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?

Goes well beyond the annotations: it discloses that comments are attributed to the integration's agent bot user (not a human owner), that the activity feed shows the agent name/mark, and that entries are tagged with the runtime via externalSource for audit. That is exactly the kind of side-effect provenance an agent cannot get from readOnlyHint/destructiveHint alone. Missing only what happens on failure 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?

Front-loaded with the action, then usage, then the threading parameter, then attribution behavior — each sentence carries distinct information. Slightly over-condensed in the final clause ('shows the agent name and mark'), and the parentId sentence partly restates the schema.

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

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

With no output schema, the one real gap is that the description never says the response returns the created comment (and its id), which an agent needs to chain threaded replies. Otherwise complete for a 4-parameter mutation whose annotations already declare the safety profile.

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

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

Schema coverage is 50% (content and entityType are undocumented in-schema). The description explains parentId's threading behavior and frames content's purpose, but adds nothing about the 16,000-character limit, the ORB-526 ticket-key form of entityId, or the process/defect entity types, so it only partially compensates.

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 ('Post a comment') and names the target entities, which distinguishes it cleanly from update_comment, delete_comment and list_comments. It is slightly incomplete: the schema's entityType enum also allows 'process' and 'defect', which the description never mentions, so an agent reading only prose may not realize those targets exist.

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

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

'Use this to record progress, ask questions, or flag blockers' gives intent-level context for the content, but never says when to prefer update_comment or toggle_reaction over creating a new comment, nor any prerequisites (e.g. write access to the entity). Usage is implied rather than prescribed.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent. The description adds genuinely useful behavioral detail: direction matters per relation, and has_design/has_diagram/has_process are normalised to work item → design/diagram/process. It omits what happens on duplicate links or error behavior, so not a 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?

Front-loaded with the core action, then constraints and alternatives in a single dense paragraph. Every clause carries information, though the long parenthetical lists of types and relation names are partly redundant with the enum definitions.

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 tool with no output schema, it covers direction semantics, normalization, same-project scope, and sibling routing. Missing is what the tool returns (link object/id) and duplicate/conflict behavior, which matters given idempotentHint=false.

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% and the three enums carry no descriptions, but the description compensates by explaining relation direction with concrete examples (test_case —covers→ story, adr —affects→ story, test_case —verifies_defect→ defect) and giving a metadata example. The re-listing of type/relation values duplicates the enum and is redundant.

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

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

States a specific verb, resource and scope: 'Create a cross-module traceability link between two entities in the same project.' It also distinguishes itself from siblings by naming create_story_relation and create_test_case_from_ac as the right tools for specific cases.

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 routes the agent away for two cases: covers_ac with metadata should prefer stride.create_test_case_from_ac, and story↔story BLOCKS/DEPENDS_ON/RELATED_TO must use stride.create_story_relation. The same-project constraint is also stated.

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

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description still adds real behavior: storyId/testCaseId/assigneeId are cross-checked to belong to the same project/workspace and echoed back in the receipt. It does not state what happens on validation failure or what error surfaces, which keeps it at 4.

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, core action front-loaded. The second sentence is dense and telegraphic (slash-separated optional params) but every clause carries information the agent needs.

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 an 8-parameter mutation tool with no output schema, the description covers the association/validation semantics and defaults but omits required-field expectations for title and projectId and any notion of what the receipt contains beyond the echoed IDs. Adequate but with clear gaps given the schema's low documentation 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 description coverage is only 13%, so the description must carry the burden; it partially does by explaining storyId accepts a ticket key like "ORB-526" or UUID and that testCaseId/assigneeId are project-scoped, plus the defaults for severity and status. It says nothing about title (300-char limit), projectId, or description (64k limit), leaving half the parameters unexplained anywhere.

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: 'File a new defect in a Stride project.' It is clearly distinguishable from create_story, create_test_case, or update_defect by the resource named. It stops short of explicitly contrasting with any sibling, so 4 rather than 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 implied (this is the way to file a defect) and defaults are noted, but there is no explicit when-to-use/when-not guidance, no statement about when a defect should be a test-case failure vs. a standalone defect, and no mention of alternatives like update_defect or restore_defect.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, and the description usefully adds the return payload ('new document id + URL') plus the docType default of 'general'. It still omits the practically important facts for a non-idempotent create: whether retrying produces duplicates, and whether project access is required — information annotations cannot carry.

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 purpose and required inputs are front-loaded in the first sentence, and the return value is stated last where it belongs. The long inline enumerations of content types and docType values are somewhat padded given the enum already exists in 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?

There is no output schema, and the description compensates by naming the return value (id + URL). Required inputs, the optional docType with its default, and the markdown body are all covered; only the injected projectId and retry/duplication behavior are unaddressed.

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

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

Schema description coverage is 100%, so all four parameters are already documented, and the description's restatement of title/markdown adds little. One useful addition is the docType default ('defaults to "general"'), but its claim that docType can be 'any label' conflicts with the schema's closed enum, which muddies rather than clarifies the 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 and resource ('Create a Library document from markdown') and enumerates the kinds of content it is meant for, so the agent knows exactly what object is produced. It does not name the write-path siblings (append_to_document, update_document) that an agent might confuse this with, so it falls short of the top score.

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

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

Usage is implied by the examples ('meeting notes, release notes, retrospectives, PRDs...') and by 'saves drafted content straight into the Library', which tells the agent this is for publishing already-drafted markdown. However there is no explicit when-not guidance and no routing to append_to_document for existing documents or update_document for edits.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, closed-world, so the safety profile is covered. The description adds genuinely useful behavior an agent could not get elsewhere: default status DRAFT, authorship by the agent bot user, and emission of an EPIC_CREATED activity event — side effects worth knowing about.

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 create action, then defaults and attribution. Every clause carries distinct information: entity type, default status, field mapping, actor, and event side 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?

For a three-parameter mutation with no output schema, the description covers defaults, authorship, and side effects, which is most of what an agent needs. It omits error/duplicate-name behavior and what the response contains, so not fully complete but solid.

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%, so the description has to carry weight; it does explain that 'description' maps to the artifact content field and reframes projectId as 'the given project'. However it says nothing about the name parameter's role or the length limits beyond what the schema already encodes, leaving one 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?

States a specific verb and resource and pins down the underlying entity ('an Artifact with artifactType=EPIC'), which separates it cleanly from siblings like create_story, create_defect, create_test_case. No ambiguity about what is being produced.

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?

Scope is implicit: it creates an epic 'in the given project', which implies project membership is required, but there is no explicit when-to-use-this-vs-another statement (e.g. epic vs story vs defect). Usage is inferable from the name and first sentence rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the DUPLICATE_LABEL failure mode and the default-color fallback, which an agent cannot get from annotations.

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

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

One tight sentence with the core action front-loaded, then defaults and error semantics in descending order of importance. 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 mutation tool with no output schema and no annotations covering failure modes, the description covers creation scope, defaulting, and the duplicate error. It does not say what is returned on success (the created label id), a minor remaining gap.

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

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

Schema coverage is 67% and the description closes much of the gap: color format and default are restated concretely, and it clarifies that name uniqueness is project-scoped. projectId's UUID role is left to the schema, which is reasonable.

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) and resource (label) plus its scope (project-scoped), and enumerates the fields involved (id, name, color). It does not explicitly contrast itself with update_label or list_labels, but the resource naming makes it readily distinguishable from sibling create_* 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?

There is no explicit 'use this when...' or named alternative, though the DUPLICATE_LABEL note implies an existence-check pattern and steers behavior. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, covering the safety profile. The description adds the project-scoped validation constraint on target ids, but says nothing about duplicate names, what is persisted, or permissions, so it only partially extends structured data.

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

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

Two tightly packed sentences: creation context first, then required fields, then optional fields and their constraint. No filler or repetition.

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

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

For an 8-parameter mutation with no output schema, the description covers the required/optional structure and the key validation rule. It omits any indication of what is returned (e.g., the new gate id) and behavior on duplicate names, which leaves a small but real gap for an agent.

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

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

It summarizes the required/optional split and lists the four criterion types, but explicitly defers units to the schema ("see the criteria property for units"), which already documents them in detail. With 75% schema coverage, this is baseline behavior with modest added value from the "matching target id" pairing rule.

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

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

States a specific verb and resource ("Create a quality gate in a Stride project") that clearly distinguishes it from update_quality_gate, get_quality_gate and run_quality_gate_check. It doesn't explicitly name those siblings, but the create verb makes the boundary obvious.

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 implies creation context and notes that the gateType target id is "validated against the project", which is a useful precondition. It never says when to use this versus update_quality_gate or when a gate is inappropriate, 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?

Annotations already declare the tool as a non-idempotent, non-destructive write, so the description only needs to add context — and it does: status defaults to PLANNED, targetDate is normalized to midnight UTC, and cross-project story ids are rejected 'for safety'. That normalization and validation behavior is real information the agent could not infer from the annotations or schema.

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

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

Three tight sentences: purpose first, then required/optional inventory, then the safety constraint. No filler, though the required/optional enumeration is somewhat redundant with the schema's own required list.

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 seven parameters and no output schema, the description leaves the agent unsure what a successful call returns (created release id? the full object?) and silent on failure behavior other than the cross-project case. For a mutation tool of this complexity, that leaves a meaningful gap, though the core creation contract is adequately covered.

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 43%, so the description must carry weight; it restates the three required fields, the PLANNED default, the ISO datetime format for targetDate, and the ticket-key/UUID acceptance for storyIds. However, it omits the schema's length and count bounds (name maxLength 200, version maxLength 100, description maxLength 64000, storyIds maxItems 500) and merely echoes the existing storyIds and targetDate property descriptions.

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

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

The description opens with a specific verb and resource ('Create a new release in a Stride project'), which cleanly separates it from siblings like create_sprint, create_story, or update_release. It never explicitly names an alternative, but the resource is unambiguous enough that an agent won't confuse it.

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 lists required and optional parameters but gives no guidance on when a new release should be created versus reusing an existing one via list_releases or modifying one via update_release. The only conditional logic offered is the cross-project rejection rule, which is a validation constraint rather than usage routing.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the write profile is covered. The description adds non-obvious state information — the sprint lands in PLANNING and requires a separate transition to start — which an agent cannot infer from annotations or schema. It omits what is returned (sprint ID), a minor 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?

Three tight sentences: action first, parameter requirements second, lifecycle consequence and next step last. No filler 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?

Covers creation semantics, required inputs, date constraints and the resulting state, which is nearly everything needed for a non-destructive create with no output schema. The one omission is whether the new sprint's identifier is returned — important since the agent will need it for the recommended transition_sprint call.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the ISO8601/midnight-UTC and endDate>=startDate constraints. The description's required/optional recap and '(ISO8601)' tags largely restate the schema, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a new sprint') and names the scope ('in a Stride project'), which cleanly distinguishes it from siblings like stride.update_sprint, stride.transition_sprint, and stride.list_sprints. No ambiguity about 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?

Explicitly routes the agent to stride.transition_sprint for the follow-up action of starting the sprint, and the PLANNING-status detail implies this is the entry point of the sprint lifecycle. It doesn't address when to prefer update_sprint over creating a new sprint, but the primary lifecycle 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?

Annotations already signal this is a non-destructive, non-idempotent write. The description adds genuinely useful behavior: it returns the new displayId and echoes accepted fields (AC ids, epic/sprint/parent/assignee) so no confirm-read is needed, and that cross-project ids are rejected. This is real value beyond the annotations.

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

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

Front-loads the core action, then the required/optional split, then behavioral notes on status and return values. Slightly redundant in listing every optional param already visible in the schema, but overall dense and efficient.

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

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

For a 13-param write tool with no output schema, the description supplies the return shape (displayId plus echoed fields) and cross-project validation, which are the key missing structured pieces. A few param-level details remain uncovered, but an agent can call it correctly from this.

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 46%, so the description must compensate. It clarifies the status category-vs-board-column alternative and the parentId ticket-key/UUID format, but several params (labels, priority, storyPoints, type, acceptanceCriteria) are left to the schema and their self-evident names, leaving the coverage gap only partially closed.

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

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

States a specific verb and resource ('Create a new story in a Stride project') and enumerates the fields it configures, so the agent knows exactly what it produces. It does not explicitly distinguish itself from siblings like create_defect, create_epic, or update_story, which leaves some ambiguity for ticket-shape decisions.

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

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

Gives clear operating guidance: required vs optional fields, the status category-or-column rule, and a named alternative (stride.list_workflow_stages) for discovering valid column names. It stops short of explicit when-not-to-use guidance, e.g. against create_defect for bugs or create_epic for epics.

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

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

Annotations only declare readOnly=false, idempotentHint=false, destructiveHint=false; the description goes well beyond them by disclosing the per-project advisory lock, cycle detection for inverse edges, and the same-project constraint. It does not say what happens on a detected cycle (error vs. silent) or whether duplicate edges are rejected despite the non-idempotent hint.

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

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

Three sentences, front-loaded with what the tool does, then constraint, then behavioral detail — no filler and nothing repeated from 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 3-parameter mutation with no output schema, the description covers project scoping, directionality, and concurrency behavior adequately. It stops short of describing failure modes (cycle detected, duplicate edge, unknown story key) that an agent would need to interpret results.

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

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

Schema coverage is 67% and the two story parameters already carry descriptions; the description's real contribution is explaining the semantics of each enum value (directed with cycle check vs. symmetric/unrestricted), which the schema does not. Because the schema does most of the work, a 3 baseline with credit for the enum meaning is appropriate.

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

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

States a specific verb and resource ('Create a directed relation between two stories') and enumerates the three relation types, so an agent knows exactly what the tool produces. It does not differentiate itself from the nearby create_cross_link or list_story_relations siblings, which keeps it from 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?

It gives useful selection context by explaining that BLOCKS/DEPENDS_ON are directed and cycle-checked while RELATED_TO is symmetric and unrestricted, which helps pick a relation type. However, it never says when to use this tool rather than create_cross_link, nor does it mention preconditions such as needing the stories to exist first.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety bar is partly covered. The description adds genuine context beyond them: cross-project ids are rejected for safety, undefined suiteId falls back to the project's first suite, and the receipt echoes suiteId/storyId/assigneeId. It stops short of saying what happens on a repeat call (duplicate vs. dedupe).

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

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

Purpose comes first, then a dense but well-ordered Required/Optional inventory with defaults inline — no filler sentences. It reads as one long block, though every clause carries 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 an 11-parameter mutation with no output schema, the description covers defaults, validation behavior, and partial return shape, which is most of what an agent needs. Gaps are duplicate-handling semantics, permission/auth expectations, and any routing hint against the sibling create_test_case_from_ac.

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 36%, so the description has to carry the load and does: it names every parameter, gives storyId's two accepted formats, explains the suiteId fallback, documents the steps item shape as { action, expected }, and lists the full enums with defaults (including the INTEGRATION default for type, which the schema itself omits).

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

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

Opens with a specific verb+resource ("Create a test case in a Stride project") and immediately enumerates the fields it writes, so an agent knows exactly what it produces. It does not, however, distinguish itself from the sibling stride.create_test_case_from_ac, which an agent could easily confuse with it.

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 required/optional split and the defaults (suiteId, priority, type, status) give implicit guidance on what a minimal call looks like. But there is no explicit when-to-use statement, no exclusion of create_test_case_from_ac, and no prerequisites such as permission or project-state requirements.

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

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

The description claims 'Idempotent per criterion' and says an already-covered criterion writes nothing, but the annotations declare idempotentHint=false. This is a direct contradiction; despite otherwise useful behavioral details about defaults and receipts, the contradiction forces a 1 under the rules.

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 purpose is front-loaded and the remaining sentences are dense with operational details: required identifiers, mode exclusivity, idempotency behavior, template/default behavior, and sibling routing. There is little filler for a complex tool.

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

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

For a six-parameter creation tool with no output schema, the description is unusually complete. It explains how to obtain ac_ ids, what each mode returns, template and suite defaults, creation defaults, and when to use the sibling tool instead.

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 already 100%, but the description adds meaningful semantics beyond the schema: acIds is capped at 50, allCriteria creates every criterion in one call, templateId supports title patterns with {{acText}} and {{storyTitle}}, and suiteId defaults to the project's first suite.

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 precise verb and resource: create test cases from a story's acceptance criteria, linked via covers_ac. It explicitly distinguishes itself from stride.create_test_case by saying to use that sibling when a case should cover a whole story instead.

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 required storyId and the mutually exclusive selection modes: exactly one of acId, acIds, or allCriteria. It also names the alternative sibling and the condition for choosing it, so an agent can route correctly without inference.

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

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

Annotations already declare this is a non-destructive, non-idempotent write, so the description is not carrying the safety burden. It still adds real behavioral value beyond them: the suiteId side effect (pre-seeds one BLOCKED result per non-deprecated case), the PLANNED default, and the constraint that the suite must be in the same project. Return payload and failure modes (e.g., duplicate names) remain undisclosed.

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

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

One dense paragraph, front-loaded with the action, then the required/optional inventory, then the recommended workflow. The parenthetical about pre-seeded results is long but every clause carries distinct information; nothing is redundant restatement of the annotation or title.

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 output schema, the description covers the creation contract, defaults, side effects, and follow-up workflow well. The notable gap is that it does not say what is returned (presumably a run ID needed for the subsequent record_test_results call), which forces the agent to discover that at runtime.

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 has to compensate, and it largely does: it restates the required/optional split, the status enum and default, and the seeding semantics of suiteId that the schema only glosses as 'must be in same project.' The name parameter's meaning and the environment values are left to the schema (environment only explained indirectly through pairKey's description).

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

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

The opening sentence gives a specific verb and resource (create a test run in a Stride project) and immediately enumerates required vs optional inputs. It positions itself in a workflow relative to stride.record_test_results, which helps separate it from recording results, but it never explicitly contrasts itself with close siblings like create_test_suite or delete_test_run.

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?

'For the normal workflow, create the run as PLANNED, then set completeRun=true on the final stride.record_test_results batch' gives concrete guidance on when to create with which status and what comes next. There are no explicit when-not conditions (e.g., when to create with status RUNNING or COMPLETED directly), so it stops short of full when/why-not coverage.

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

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

Annotations already cover safety properties (readOnly=false, destructive=false, idempotent=false). The description adds useful behavior beyond annotations: duplicate name refusal, returned suite id, and optional categorization. It could say more about error handling but is solid.

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

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

Front-loaded purpose, followed by prerequisite, optional fields, return value, and a key constraint. It is compact and every sentence adds useful information.

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

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

Given no output schema, the description explains the return value, the duplicate-name refusal, and the prerequisite relationship. It provides enough context to call the tool correctly without needing extra documentation.

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

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

Schema coverage is 100%, so the parameters are fully documented in the schema. The description only restates that description and category are optional and that category is free-text, adding little beyond 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?

States a specific verb and resource ("Create a test suite") and immediately clarifies its role as the container for test cases, distinguishing it from related tools like create_test_case and list_test_suites.

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

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

Explicitly says when to use it: when a project has no suites and create_test_case needs a suiteId. It names list_test_suites as the way to check and makes the prerequisite relationship 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?

The annotations already declare destructiveHint=true and idempotentHint=true, so safety and repeat-call semantics are covered. The description adds one genuinely valuable, non-obvious fact — inline references are not stripped. However it never says whether the deletion is permanent (no restore_attachment sibling exists) or what happens on a missing attachmentId, leaving the irreversible nature implied only by the annotation.

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

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

Two sentences, no filler, with the core action front-loaded ahead of the caveat. The parenthetical aside is slightly dense but earns its place by naming the alternative endpoint.

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, non-open-world mutation with rich annotations and no output schema, the description supplies the one behavioral subtlety an agent would otherwise get wrong. Only the irreversibility/error behavior is missing.

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

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

Schema description coverage is 100% and both parameters (storyId, attachmentId) are well documented with format examples, so the schema carries the load. The description adds no parameter-level meaning, which is acceptable but merits only 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?

States a specific verb and resource ('Remove an attachment from a story'), which cleanly separates it from stride.upload_attachment and stride.list_attachments. It stops short of naming those siblings explicitly, so 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?

Gives a concrete condition and alternative: use the REST endpoint when inline reference cleanup matters. That is genuine routing guidance. It does not cover prerequisites (permissions, whether the attachment must be listed first) or when-not-to-use relative to in-server alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's burden is lower, yet it still discloses a non-obvious server-side guard: deletion is restricted to agent-authored comments regardless of session role. That is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Two tight sentences, no filler; the core action leads and the restriction follows immediately as rationale.

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 destructive tool, the description plus annotations cover everything needed: safety profile, idempotency, the authorization guard, and the identity of the target. No output schema exists, but a delete's return value is not decision-relevant here.

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

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

The single commentId parameter is documented at 100% schema coverage with its UUID type and meaning. The description adds no further syntax or format guidance beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Delete ... comment") plus a scoping qualifier ("agent-authored") that cleanly separates it from update_comment, list_comments, and create_comment in the sibling set. An agent knows exactly which operation this performs.

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

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

Gives an explicit negative condition — refuses human-authored comments even with OWNER/ADMIN — which tells the agent when not to call it and that elevation won't help. It doesn't name a sibling alternative for moderation, but the exclusion is concrete and actionable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so safety profile is covered. The description adds real context beyond that: it scopes the operation to cross-module links only and points at list_cross_links as the id source. It doesn't say what happens on an unknown/stale id, which keeps it from a 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?

Two compact sentences: the action and its input come first, the disambiguation follows. No filler, no repetition of the title.

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 one-parameter delete with rich annotations and no output schema needs no more than this. The description covers what it removes, how to identify the target, and when not to use 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 100% and the single parameter is documented as a cross-link UUID, so the schema does the heavy lifting. The description's 'Required: linkId' merely restates the required field without adding format or validation detail beyond the schema.

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

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

States a specific verb (remove) and resource (cross-module link), identifies the sole parameter, and explicitly contrasts itself with stride.delete_story_relation. An agent can distinguish it from delete_story_relation and delete_attachment 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?

Gives both a positive routing rule (use this for cross-module links) and an explicit exclusion with the correct alternative named for story↔story relations. It even tells the agent where to obtain the linkId.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description is not obligated to restate that — yet it adds real substance beyond them: the record is not physically removed (deletedAt is set), repeat calls yield ALREADY_DELETED, and notably the cleanup-cron clock is not refreshed. That last detail is non-obvious side-effect information an agent could not infer from any structured field.

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 the core action front-loaded and the idempotency/cron nuance compactly parenthesized. No sentence is filler and nothing 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 one-parameter mutation with no output schema, the description covers the semantics of the operation and the repeat-call outcome thoroughly. It leaves minor gaps: whether a deleted defect can be recovered (restore_defect) and what happens if the ID is unknown or already deleted beyond the ALREADY_DELETED code.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that defectId is the UUID of the defect. The description adds no additional meaning about the parameter (e.g. whether the UUID must reference a non-deleted defect), so the baseline of 3 applies.

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

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

States a precise verb and resource ('Soft-delete a defect') and immediately pins down what 'soft' means (sets deletedAt). This distinguishes it from a hard-delete sibling and from update_defect without needing to open the schema.

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

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

It makes clear this is the reversible/soft removal path and that repeat invocation is safe, which is exactly the usage context an agent needs before deleting. It stops short of naming restore_defect as the undo path or stating prerequisites such as ownership/permission requirements.

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

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

Adds substantial context beyond the annotations: it discloses that this is a soft delete setting deletedAt, that the operation is recoverable via stride.restore_design, that cross-links are preserved, and that repeat calls return a no-op success. These details are not inferable from destructiveHint or idempotentHint alone.

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

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

Four compact sentences, each delivering distinct information: operation semantics, recovery path, use case, side effects, and idempotent behavior. No filler or repetition.

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

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

For a single-parameter destructive tool with no output schema, the description covers the mutation model, recoverability, preservation of relationships, and repeat-call behavior. Nothing an agent needs in order to call it safely and correctly appears 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 single parameter has 100% schema description coverage ('UUID of the UI design'), so the schema already carries the semantics. The description does not add format constraints or edge cases for designId; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Soft-delete a UI design and its variants') and clarifies the scope includes variants. An agent can distinguish it from sibling delete tools like delete_diagram or delete_document without opening a schema.

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

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

Provides a clear usage context ('Use to clean up a design generated in error') and points to the recovery path (stride.restore_design). It stops short of explicit exclusions or comparisons to sibling delete tools, but the intended scenario is unambiguous.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantive behavior beyond them: it is a SOFT delete via deletedAt, it is recoverable through stride.restore_diagram, and re-deleting returns a no-op success rather than an error. That is exactly the extra context an agent needs before invoking a destructive tool.

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

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

Three short sentences, front-loaded with the core action and mechanism, followed by the use case and the edge-case behavior. 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 mutation with no output schema, the description covers action semantics, recoverability, and idempotent edge-case behavior, while annotations carry the safety profile. Nothing material to a correct call is missing.

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

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

Only one parameter, diagramId, and the schema documents it at 100% coverage ('UUID of the diagram'). The description adds nothing about the identifier format or sourcing, so baseline 3 applies.

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

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

States a specific verb+resource ('soft-delete an architecture diagram') and immediately clarifies the mechanism (sets deletedAt) and the counterpart tool (stride.restore_diagram). This separates it cleanly from siblings like delete_design, delete_process, and restore_diagram.

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

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

Gives a concrete use case ('clean up a diagram generated in error') and names the recovery alternative stride.restore_diagram. It does not spell out when not to use it (e.g., diagrams referenced by other artifacts), but the conditional context is clear.

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

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

Adds substantial behavior beyond the annotations: the document is removed from the Library list and from stride.search_documents, it remains restorable by a human from an archived view, and the call is idempotent on an already-archived document. This resolves the tension between destructiveHint=true and the soft-delete semantics, which annotations alone could not convey.

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

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

Three short sentences, front-loaded with the action and its real semantics, followed by side effects and the idempotency guarantee. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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 mutation with no output schema, the description covers what is affected (Library listing and search index), reversibility, idempotency, and the unavailability of hard deletion. Nothing an agent needs in order to call it safely is missing.

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

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

The schema documents the single documentId parameter at 100% coverage, so parameter meaning is already fully specified by the structured data. The description adds no further detail about the identifier format or resolution, which is acceptable at this coverage level but earns only 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?

States a specific verb and resource ('Archive a Library document') and immediately clarifies that the name 'delete' actually means soft-archive, with examples of the document types covered. An agent can distinguish this from sibling delete_* tools and from update_document without opening a schema.

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

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

Gives clear context for use (removing a document from the Library and from search) and an explicit exclusion: permanent purge is not available to agents, so an agent should not look elsewhere for hard deletion. It does not point at sibling tools such as stride.restore_document or update_document as alternatives, which keeps it 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?

Goes well beyond the annotations by disclosing exactly what gets written (deletedAt), what cascades (dependent stories have epicId nulled), what is explicitly preserved (stories themselves are not deleted), and that the operation is atomic. The annotation hints destructive/idempotent, but only the description tells the agent the blast radius.

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

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

Three tight sentences with the operation front-loaded and the cascade consequence placed where a reader will see it. No filler; the parenthetical clarifying that stories survive is well placed rather than wasteful.

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

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

For a single-parameter mutation with rich annotations and no output schema, the description covers what an agent needs to predict the effect. The only meaningful gap is not saying whether restore_epic can undo the tombstone or how a nonexistent epic is handled.

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

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

Schema description coverage is 100% and the single epicId parameter is fully documented in the schema as a UUID. The description's reference to 'epicId' concerns the story field being nulled, not the input, so it adds no parameter syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Soft-delete an epic') and immediately qualifies it as a soft delete, which cleanly separates it from the sibling delete_* tools and points toward restore_epic as the inverse. The verb+resource+modifier combination is unambiguous.

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

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

The description makes the soft-delete nature and idempotency clear, which implies 'use this when you want the epic tombstoned but recoverable,' but it never explicitly names restore_epic or states when to prefer it over other epic operations. Guidance is implied rather than stated.

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

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

Annotations already flag destructiveHint/readOnlyHint/idempotentHint, but the description adds what annotations cannot: the deletion does not scrub the label name from stories because story labels live as a string array. That is precisely the kind of hidden side effect an agent must know before deleting.

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, both load-bearing: the first states the action and its key limitation, the second routes to the follow-up tool. No filler or restated name.

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 destructive tool this covers everything: what is deleted, what is NOT deleted, and how to do the remaining cleanup. No output schema is needed since deletion has no meaningful return to describe.

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

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

Only one parameter (labelId), fully documented in the schema as a UUID, so the description needs no compensation. It adds no extra parameter detail, but none is warranted for a single required 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?

States a concrete verb and resource ('Delete a Label row') and immediately scopes it: metadata only, not the story-side string array. That distinction separates it from the other delete_* siblings and from update_label.

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 alternative path for the adjacent task ('Use bulk_update_stories with labels.mode=remove to clean up story-side associations'), giving the agent a routing rule rather than leaving it to guess which tool handles story labels.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's real contribution is the soft-delete semantics ('sets deletedAt; recoverable'), which the annotations do not convey and which materially changes how an agent reasons about risk. The 'no-op success on an already-deleted row' sentence largely restates idempotentHint=true, so it adds less than the first two clauses.

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

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

Three short sentences with no filler: what it does first, when to use it second, edge-case behavior last. Every clause carries distinct information and the destructive/soft-delete nature is front-loaded.

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

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

For a single-parameter delete with no output schema, the description covers the mutation semantics, reversibility, the recovery tool to call next, and the already-deleted edge case. There is nothing an agent needs in order to invoke this correctly that is missing.

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

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

Only one parameter (processId) and schema coverage is 100%, with the schema itself describing it as 'UUID of the process model.' The description adds no format hints or validation notes beyond the schema, which is acceptable at this coverage level but is not above 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?

States a specific verb and resource ('Soft-delete a BPMN process model') and immediately qualifies the scope by naming the recovery sibling stride.restore_process. An agent can tell this apart from stride.list_processes, stride.get_process, and the many other delete_* tools 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?

'Use to clean up a process generated in error' gives a concrete selection condition, and the reference to stride.restore_process points at the alternative for the undo case. It stops short of stating when-not to use it (e.g. processes in active sprints or with dependent artifacts), so it is clear context rather than a full routing rule.

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?

Goes well beyond the destructiveHint annotation: it explicitly says the delete is a HARD delete, that QualityGate has no soft-delete so there is no restore path, and that evaluation-event history is removed as a side effect. That is exactly the consequence an agent needs before mutating.

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 permanence warning and the cascade effect. Every clause carries information; 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 destructive tool with full annotation coverage and no output schema, the description covers the essentials. Minor gap: no mention of permissions/authorization requirements or what the call returns (e.g., confirmation payload).

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

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

Only one parameter, and the schema documents it at 100% coverage ('UUID of the quality gate'). The description adds nothing about the id format or where to obtain it, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Permanently delete a quality gate') and clarifies the scope of deletion down to the evaluation-event history. It doesn't explicitly name a sibling, but the delete semantics distinguish it from update_quality_gate and run_quality_gate_check.

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 word 'delete'; there is no explicit when-to-use guidance, no mention of the alternative of disabling/deactivating a gate via update_quality_gate, and no warning about when not to call it.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description goes further: it discloses that the delete is soft (sets deletedAt), that it is recoverable, and that calling on an already-deleted row returns a no-op success. That edge-case behavior is genuinely non-obvious and adds real value beyond the annotations.

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

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

Two tight sentences with zero filler; the soft-delete semantics are front-loaded and the recovery/idempotency notes follow logically.

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

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

For a single-parameter mutation with rich annotations and no output schema, the description covers everything an agent needs: what it does, that it's reversible, how to reverse it, and the already-deleted edge case.

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

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

Schema coverage is 100% and the single parameter (releaseId UUID) is fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Soft-delete a release') and immediately clarifies the mechanism (sets deletedAt) versus a hard delete. This cleanly distinguishes it from siblings like stride.restore_release, which it names 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?

Explicitly points to stride.restore_release as the recovery path, giving the agent a clear alternative for undo. It doesn't spell out prerequisites (permissions, whether the release must be in a certain state), so it stops short of full when/when-not guidance.

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

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

Annotations only say destructive and idempotent; the description goes far beyond by disclosing that the delete is soft, that it atomically unassigns all stories (sprintId set to null), and that restore only re-assigns stories still unassigned. It also corrects a likely false assumption that cancelling unlocks 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?

Four tight sentences, front-loaded with the state-machine precondition, then exclusions, then the side effect. No filler and nothing deferred to the end that an agent needs early.

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 destructive tool whose annotations cover safety and idempotency, the description supplies everything needed: eligibility rule, side effects, recovery path, and the alternative for out-of-scope cases. No output schema is needed since the effect is fully described.

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 sprintId parameter is fully typed, so the schema carries most of the burden. The description still adds value by constraining the valid domain of that UUID to sprints in PLANNING, which the schema does not express.

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 ('soft-delete') and resource ('a sprint') plus an explicit scope restriction (must be in PLANNING). An agent can distinguish this from transition_sprint and restore_sprint 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?

Gives explicit when-to-use (PLANNING sprints), when-not (ACTIVE can never be deleted, CANCELLED is permanent), and names the correct alternative for running sprints: transition_sprint with to="CANCELLED". It also points forward to restore_sprint for recovery.

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?

Goes well beyond the annotations: sets deletedAt, exposes the nightly cleanup-cron hard-delete after 7 days, and documents the ALREADY_DELETED soft error on tombstoned rows. This is exactly the mutation lifecycle and error behavior an agent needs before calling a destructive 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?

Four short sentences, each contributing distinct information (soft semantics, grace window, undo path, error code), with the core behavior front-loaded.

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

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

For a single-parameter destructive tool with no output schema, the description covers lifecycle, reversibility, timing, and error semantics, leaving nothing material an agent needs unstated.

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 storyId description already explains the ticket-key/UUID formats, so the schema carries the load. The description adds only the tombstoned-row context, not parameter-level detail, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Soft-delete a story.' This immediately distinguishes it from the other delete_* siblings and from restore_story, and the 'soft' qualifier gives the agent the key semantic difference from a hard delete.

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 stride.restore_story as the undo path and the 7-day grace window as the condition for it. It doesn't discuss when to prefer other delete variants, but for a delete tool the alternative that matters (undo) is covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered by structured data. The description adds a workspace-scoping claim, but that claim references a 'denormalised projectId' that is not a parameter in the schema, which is more confusing than clarifying, and it never states whether the deletion is permanent (no restore_story_relation sibling exists).

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

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

Three short sentences, front-loaded with the action, then scope, then the discovery hint. Zero padding, though the middle sentence about projectId adds ambiguity rather than 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 single-parameter delete whose annotations already convey destructiveness and idempotency, the description covers purpose, scoping and id discovery. The unverifiable projectId remark is the only loose end, and no output schema or return-value explanation is needed here.

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

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

Schema coverage is 100% and the schema already says 'Relation UUID', so the description only needs to add provenance. It does that usefully by naming list_story_relations as the source of the id, which is the baseline-3 level of added value.

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 ('Delete a story relation by id'), which is unambiguous and distinct from siblings like create_story_relation and delete_cross_link. It does not explicitly contrast with delete_cross_link, so it stops just short of full sibling differentiation.

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

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

Explicitly points to stride.list_story_relations as the way to obtain a valid relation id, which is actionable pre-call guidance. It gives no 'when not to use' condition or note on the absence of an undo/restore counterpart.

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

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

Annotations only say destructiveHint=true and idempotentHint=true; the description adds the crucial nuance that deletion is soft (deletedAt), that repeat invocations yield ALREADY_DELETED, and that they don't refresh the cleanup-cron clock. Those details — especially the cron-clock caveat — are non-obvious and materially affect correct invocation.

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 operation, then the mechanism, then the recovery path. No filler and no repetition of the title.

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 soft-delete with no output schema, everything needed is present: semantics, idempotency behavior, error signal, and how to reverse it. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter (testCaseId, UUID), so the schema already carries the full burden. The description adds nothing about the parameter's format or source, so the baseline 3 applies.

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

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

States a specific verb plus resource ('Soft-delete a test case') and immediately disambiguates the flavor of deletion by describing the deletedAt mechanism. An agent can distinguish it from stride.delete_test_run, stride.delete_test_suite, and stride.delete_test_case's own restore path 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 description names the reverse operation explicitly ('Restore with stride.restore_test_case') and warns that repeat calls return ALREADY_DELETED, which effectively tells the agent not to retry. It stops short of an explicit when-not-to-use statement, so it's clear context rather than a full routing rule.

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

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

Annotations only flag destructiveHint=true; the description supplies the consequences an agent actually needs: hard delete with no soft-delete recovery, cascading removal of all recorded results, rollback of test case verdicts to the previous surviving result or clearing when none remains, and child re-runs surviving with the parent link severed.

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

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

Three dense sentences, each earning its place: the irreversibility warning is front-loaded, followed by cascade effects and the least-obvious side effect on child re-runs. No filler or restatement of the tool name.

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 destructive tool with no output schema, the description covers everything that affects a safe call: permanence, cascade scope, and downstream state changes. Remaining details (e.g., the empty return payload) are trivial relative to what is disclosed.

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% on the single required testRunId (UUID of the test run), so the schema carries the parameter documentation. The description adds no format or lookup guidance for testRunId, making the baseline 3 appropriate.

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

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

States a specific verb and resource (delete a test run) plus its full scope (every result it recorded), and 'HARD delete' distinguishes it from any recovery path. An agent can immediately tell this apart from stride.delete_test_case, stride.delete_test_suite, or stride.record_test_results.

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 explicit 'no restore' warning gives clear decision context for when this tool is appropriate versus seemingly similar cleanup, and the sibling list confirms there is no restore_test_run counterpart. It stops short of naming an alternative for agents who merely want to remove individual results rather than the whole run.

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

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

Annotations already declare destructiveHint and non-readOnly, and the description adds substantial context beyond them: no soft-delete exists, the cascade deletes all test cases and their results, test runs survive but lose their suite link, and the refusal-then-force flow with returned counts. This is exactly the mutation detail an agent needs before invoking.

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

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

Three sentences, each carrying distinct payload: the irreversibility warning is front-loaded in capitals, followed by cascade consequences, then the force gate. No filler and no repetition of the annotations or schema.

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

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

For a destructive two-parameter tool with no output schema, the description covers destruction scope, side effects on related entities, the failure mode, and the escalation path. Even the returned counts are mentioned, so nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so both parameters are documented in structured form and the baseline would be 3. The description adds operational meaning over the schema by framing force as the release valve for a non-empty suite and prescribing a human-confirmation workflow, though it does not describe testSuiteId beyond what the schema says.

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 ('PERMANENTLY delete a test suite') with an explicit scope qualifier (hard delete, no restore). This immediately distinguishes it from update_test_suite and from the restore_* family of siblings, so an agent need not open a schema to know what it does.

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

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

Gives a clear precondition: a non-empty suite refuses unless force: true is passed, and force requires explicit human confirmation with counts relayed back first. It does not explicitly name a sibling alternative (e.g., delete_test_case for partial cleanup), so it falls short of a full when/when-not routing statement.

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

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

Goes well beyond the annotations: it explains exactly what an idempotent retry returns (same executionId, alreadyEnded: true) and that it never opens a new session, and it discloses the hidden 30-minute auto-TIMED_OUT rule. That timeout behavior is server-side state an agent could not infer from the schema or hints.

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

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

Three sentences, each carrying distinct payload: purpose, idempotency contract, timeout behavior. Front-loaded with the core action and 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?

With no output schema, the description still tells the agent what comes back (executionId, alreadyEnded flag) and covers the edge cases that matter for a mutation: retries and stale sessions. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so outcome/error/summary semantics are already documented in the schema, including the failure-requires-error rule. The description only restates the outcome→status mapping; it adds no new parameter guidance, so the baseline 3 applies.

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

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

States a specific verb and resource: "Closes the current agent execution row at the end of a piece of work," plus what it records (SUCCEEDED/FAILED on the audit dashboard). No sibling tool in the list does anything comparable, so the agent can distinguish it immediately.

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?

"At the end of a piece of work" gives a clear timing/context cue for invocation. It does not name any exclusion or point to a counterpart (e.g. task-completion or next_task flows) that would tell the agent when not to close, so it stops short of full alternative routing.

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

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

The description adds substantial behavior beyond the annotations: it persists a draft diagram in the Design module, links it to the story, can run for about four minutes, returns "still running" with a toolCallId after roughly 52 seconds, continues in the background, ignores duplicate calls while running, and saves nothing if cancelled. These details are critical for an agent invoking a long-running, non-read-only operation.

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

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

The description is front-loaded with the purpose, then covers the diagram type and story identifier, then the async behavior. It is somewhat long, but nearly every sentence carries operational value for a complex long-running tool; minor tightening is possible but not required.

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 tool with no output schema and complex async behavior, the description is largely complete: it explains persistence, linking, polling, repeated calls, and cancellation outcomes. The main remaining gap is that it does not describe the exact shape of a successful saved result beyond saying it is returned by stride.get_tool_call_status.

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

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

Schema description coverage is 100%, so the schema already documents storyId, diagramType, and instructions thoroughly, including the enum values and AUTO default. The description reinforces the ticket-key/UUID format and type selection but does not add meaningful parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: it generates an architecture diagram for a story using the story's title, description, and acceptance criteria. The word "architecture" and the diagram-type list distinguish it from sibling generation tools such as stride.generate_process and stride.generate_ui_design.

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 usage context: identify the story by ticket key or UUID, choose a diagram type or AUTO, and optionally pass extra instructions. It also explains the async continuation path via stride.get_tool_call_status and repeat-call behavior, though it does not explicitly compare itself against the other generate_* siblings.

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

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

Extremely explicit about behavior beyond annotations: ~4 minute runtime, the 52-second 'still running' + toolCallId pattern, background completion, deduplication of repeat calls for the same story/option, and that cancelling saves nothing. This directly informs the agent's retry/poll strategy, which annotations alone (openWorldHint, non-idempotent) could not convey.

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

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

Core purpose is front-loaded in the first clause, followed by the long-running/polling mechanics. The later sentences are long and compound (several clauses about repeat calls, waiting, and cancellation), but each carries non-redundant operational information.

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

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

Given no output schema, the description does explain the intermediate return ('still running' + toolCallId) and that the final result is saved, plus the how-to-follow-up path via stride.get_tool_call_status. It stops short of describing the shape of the final saved-process result, a minor remaining gap.

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

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

Schema description coverage is 100% and already documents all three parameters including the detail enum. The description mostly restates those semantics (ticket key example, detail options) without adding format or constraint details beyond the schema, so baseline 3 applies.

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

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

States a specific verb and artifact: generates a BPMN process from a story's title/description/acceptance criteria, validates with bpmnlint, and persists a draft linked to the story. This clearly separates it from siblings like generate_diagram, get_process, or list_processes.

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

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

Gives the input precondition (story identified by ticket key or UUID) and optional detail/guidance knobs. It does not explicitly contrast with generate_diagram or explain when to regenerate vs. refine an existing process, but the usage context is clear.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false — they say nothing about latency or async behavior. The description adds exactly that: up to ~4 minutes runtime, a ~52-second cutoff returning 'still running' with a toolCallId, background completion that saves the result, concurrent same-story calls that start nothing, and the warning that cancelling the call 'stops the run and saves nothing'.

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

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

Purpose and persistence are front-loaded in the first sentence, and the long async guidance is packed with operational detail rather than filler. It is on the long side (eight sentences) and the 'still running' repeat-call behavior is restated twice, but that repetition carries real information about concurrent calls.

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

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

With no output schema, the description still explains what happens to the result (saved as a design the team can preview/refine/attach) and how to retrieve it via get_tool_call_status. The one gap is that it does not describe the shape of a successful response (design id, option list), which an agent would want when no output schema exists.

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

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

Schema coverage is 100%, so the schema already documents all three parameters — including the 'ORB-526' preferred format, the 1-5 count range and default, and the 'dark mode, sidebar layout' instructions example. The description repeats those same facts without adding new semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Generate AI UI-mockup options (HTML/CSS) for a story') plus the persistence effect, so an agent immediately knows this creates new design artifacts. Sibling-name confusion with refine_ui_design, list_designs, or link_design is avoided because the description names the output artifact (a design) and the source (story title + 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?

Gives concrete usage context: identify the story by ticket key or UUID, optionally pass count 1-5 and free-text instructions, and explicitly routes long-running runs to stride.get_tool_call_status with the exact waitSeconds 40 pattern. It does not explicitly say 'use refine_ui_design instead when modifying an existing design', so the new-vs-refine boundary is only implied by the parenthetical 'for a refine, the same option'.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real behavioral context by naming the returned fields and specifying that the 'versions' facet returns published snapshot metadata ordered newest first. It does not mention error behavior for an unknown id or permission requirements.

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 tightly packed sentences: what it returns first, then the optional facet with its semantics, then id provenance and the related linking tool. No filler or redundancy.

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

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

There is no output schema, and the description compensates by enumerating the returned fields, plus it covers the optional facet, its ordering, id sourcing, and a natural next step. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents both parameters and a 3 would be acceptable baseline. The description adds meaning beyond the schema by explaining what the versions facet actually contains and its ordering, and reinforces the provenance of adrId.

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?

Uses a specific verb (fetch) plus a precisely scoped resource (one architecture decision record) and enumerates the returned fields. The 'one' plus the pointer to stride.list_adrs makes it distinguishable from the list sibling without opening either schema.

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

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

Explicitly says the id must come from stride.list_adrs, which tells the agent the list tool is the prerequisite alternative, and points to stride.create_cross_link as the follow-up for linking. It does not state any when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that by naming the fields returned, though it says nothing about error behavior for a missing 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?

One sentence, zero waste, with the resource and the id scoping front-loaded and the return contents trailing. Nothing to trim.

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?

There is no output schema, so listing the returned fields is genuinely needed and is done well. For a single-parameter read tool with full annotation coverage, the remaining gap (behavior on unknown id) is minor.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. 'By id' does communicate that defectId is the defect identifier, but it adds no format, source, or lookup guidance beyond that minimal hint.

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 (fetch) and resource (defect) scoped by id, and enumerates what comes back (description, severity, status, linked story and test case). It is clearly distinguishable from the sibling list_defects by its single-item-by-id framing, though it never names the sibling 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?

The 'by id' phrasing implies you should call this when you already have a defect identifier, but there is no statement of when to prefer it over list_defects or update_defect, and no exclusions or prerequisites. Usage is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is free. The description adds real context beyond that: the response is a bundled multi-section payload, lint findings are precomputed/'already known', and the payload can be narrowed via include — which matters for a potentially large read. It doesn't mention payload size limits or failure behavior for bad IDs.

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: the first front-loads the payload contents, the second front-loads the usage condition and the parameter hint. No filler, and every clause carries 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?

With no output schema, the description carries the burden of describing return shape, and it does so by enumerating all five section types that the include enum also names. Combined with the pre-call guidance, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and both properties are documented, including the enum values for include. The description's note that 'include narrows the sections returned' restates the schema rather than adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource plus full payload enumeration: screens, navigation flow, React + Tailwind components, self-contained HTML, and lint findings. An agent can distinguish this from generate_ui_design or list_designs 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?

'Use this before implementing a screen from a design' gives a clear triggering context, and 'replaces reading the raw HTML and guessing at the structure' explains the value relative to a manual approach. It stops short of naming sibling tools (e.g. refine_ui_design, generate_ui_design) as alternatives, so there is no explicit exclusion rule.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behaviour, so the description doesn't need to repeat them; it adds real value by describing the return shape (components with type/technology/description, connections with resolved endpoint names) and the deliberate exclusion of canvas geometry. Missing only error behaviour for unknown or deleted diagram ids.

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

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

Front-loaded with the action and the returned payload, then the geometry caveat, then the sibling pointers. Every clause earns its place; nothing repeated or 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?

With no output schema, the description carries the return-shape burden and does so competently, plus it names the diagram taxonomy and id source. It would be complete at 5 with a note on what happens for a stale id or an unauthorized diagram.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents `diagramId` as a UUID. The description contributes only the hint to obtain ids from list_diagrams, which is a baseline-level addition rather than new format or constraint detail.

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

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

States a specific verb and resource (read one architecture diagram), enumerates the diagram kinds covered, and describes exactly what is returned: a semantic graph of typed components and named connections, with canvas geometry omitted. That distinguishes it immediately from list_diagrams and from the broader context 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?

Explicitly points to list_diagrams for id discovery and to the `diagrams` section of get_story_context for story-linked diagrams, which is clear routing guidance. It stops short of saying when not to use it, e.g. when a design or process document would be the better source.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful context that it returns the FULL text (not a summary or metadata) and where it fits in a read-then-act workflow; it lacks error behavior for unknown ids, so not a 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?

Two tight sentences with no waste, front-loading what is returned before the workflow hint. Every clause earns its place.

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

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

Complete for a one-parameter read tool: what it does, what it returns (full text), and when to call it are all present, with annotations covering safety. No output schema exists, but 'full text' sufficiently signals the return; only minor gaps like error/missing-id behavior remain.

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

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

Schema coverage is 100% and the single documentId is already documented as a UUID, so the schema does the heavy lifting. The description's 'by id' adds only marginal meaning beyond that; baseline 3 is appropriate.

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

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

States a specific verb (read) and resource (full text of a Library document), gives concrete examples of document types, and scopes it by id. It clearly distinguishes itself from metadata/search tools like stride.search_documents.

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 routes the agent: use after stride.search_documents and before summarizing or creating stories/tasks from the content. It gives a clear workflow position but does not state when not to use it (e.g., use append_to_document or update_document instead of reading).

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

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

Annotations already declare this a safe, idempotent, closed-world read, so the description's job is to add payload behavior — and it does: aggregated story rollup, status breakdown, distinct sprint set, and the fact that stories come back as slim stubs with a named field set. It does not say what happens with an unknown epicId or whether story stubs are truncated, which keeps it out of the top score.

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. Purpose and return contents come first, the pivot guidance comes second, and every clause carries new information (rollup metrics, stub field list, next-step tools).

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 carry the return contract, and it does so comprehensively — aggregate shape plus stub field list. Minor gaps remain around failure behavior for a bad id and whether the story stub list is bounded, but nothing essential to a correct call is missing.

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

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

There is a single parameter at 100% schema description coverage ('UUID of the epic'), so the schema fully carries parameter meaning. The description adds only the phrase 'by id', which restates rather than extends the schema — baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Get an epic by id') and immediately enumerates what the response contains: rollup counts, points, status breakdown, and distinct sprints. That detail distinguishes it cleanly from list_epics (enumeration) and get_story (single story), so an agent can select it 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 rather than stated: fetching one epic by its id. The only explicit routing advice points downstream ('pivot to specific stories with get_story or update_story'), not at how to choose this tool over siblings like list_epics or get_story_context. It never says when not to use it or where the epicId comes from.

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

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

Annotations already declare this as a safe read (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description nonetheless adds meaningful behavior by stating the 50-key ceiling and describing what comes back (source/schema/traffic excerpts per finding), which matters because there is no output schema. It stops short of saying how missing or invalid keys 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?

Two sentences with zero filler: the operation and its keying come first, the return payload second. Nothing is duplicated or 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 two-parameter read tool with no output schema, the description supplies the essential return-content picture and the batch limit. Remaining gaps are partial-result and error behavior, which are minor but non-trivial for a batch-key lookup.

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 both parameters and the 1–50 item bounds are already documented. The description's key example (EV-000123) and 50-key limit largely restate schema content rather than adding new semantics, so baseline 3 applies.

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

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

States a specific verb+resource: fetch citation evidence snippets by key for a named legacy system, and clarifies it is the excerpt backing a cited finding. That is clearly distinct from siblings like get_legacy_system or get_legacy_parity, though the description 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?

Usage is implied by 'backing each cited finding' and the key format, but the description itself gives no when-to-use/when-not guidance and does not name get_legacy_system as the place to obtain keys — that pointer exists only in the schema. An agent must infer the call sequence.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context by specifying that it returns a rollup from the latest complete characterization run pair, which tells the agent about data dependency and freshness. It does not contradict annotations.

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

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

A single, well-structured sentence that front-loads the purpose and packs essential details without any waste.

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

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

For a read-only tool with one parameter and no output schema, the description is nearly complete. It omits what happens if no complete run pair exists, but the annotations and schema cover most needs.

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 parameter legacySystemId is fully documented in the schema. The description does not add meaning beyond the schema for the parameter, so the baseline score of 3 is appropriate.

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

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

The description precisely states the return content (overall %, regression count, per-rule breakdown) and the data source (latest complete baseline/target characterization run pair), clearly distinguishing this rollup tool from siblings like get_legacy_system or get_legacy_evidence.

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 context of a 'latest complete baseline/target characterization run pair', but the description does not explicitly state when to use this tool versus alternatives such as get_legacy_evidence or trigger_legacy_reanalysis, nor does it mention prerequisites or 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?

Annotations already cover the read-only, idempotent, non-destructive profile, but the description adds meaningful behavior: the return is a plain-text bundle, facets can be absent with a facetNotes entry explaining why, and structuredContent.registration reveals whether analysis is even possible. The only gap is no mention of bundle size limits or truncation for large systems.

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

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

The core action is front-loaded in the first clause and every sentence carries information, with no filler. Density is high, though long em-dash-and-parenthetical sentences make it harder to scan than it could be.

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

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

With no output schema, the description carries the burden and does: it itemizes the bundle's sections, names the structuredContent.registration flag and its implication, and explains facet absence semantics. An agent can call this correctly and interpret the result from the description alone.

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

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

Although schema coverage is 100%, the schema only lists the four enum strings, while the description explains what each yields: 'requirements' gives per-family counts plus FR ids, 'plan' a latest plan summary, 'progress' a modernization rollup, and 'evidence_index' the exact keys accepted by stride.get_legacy_evidence. That is substantial semantic value beyond the enum names.

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

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

States a specific verb and singular resource ('Fetch one legacy system') and enumerates the bundle's contents (components, integrations, business rules, data flows, scores, analysis highlights). The singular 'one legacy system' plus the get_ prefix cleanly separates it from the list_legacy_systems sibling, and the mention of evidence keys points at get_legacy_evidence without confusion.

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 by explaining what each optional facet adds and by noting that a manual system without a connected repo 'cannot be analysed until a human connects one', which is a real precondition. However, it never states explicitly when to call this versus list_legacy_systems, get_legacy_evidence, or get_modernization_repo_status, so the agent must infer the routing.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the description only needs to add context – and it does, by defining 'staleness' (code changed since last analysis) and by disclosing the manual-registration branch of behavior. It could go further on what an 'in-progress ingest' means operationally, but this is solid added 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, front-loaded with the primary read, then the edge case. It is dense but every clause carries information; the only minor cost is that the parenthetical about manual registration is slightly buried mid-sentence.

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

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

With no output schema, the description must convey return content, and it does via the enumerated fields plus the no-repository outcome. An agent can call this correctly knowing only legacySystemId; the remaining gap is the format of the returned status values, which is minor.

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

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

There is a single required parameter with 100% schema description coverage ('UUID of the legacy system'), so the schema carries the semantics. The description adds nothing about the identifier itself, which is the expected baseline of 3.

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

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

The description opens with a specific verb+resource ('Read the connected GitHub repository status for a legacy system') and enumerates exactly what is returned: owner/repo/branch, link status, staleness, in-progress ingest. That is clearly differentiated from siblings like get_legacy_system (system metadata) and trigger_legacy_reanalysis (a mutation).

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 pre-analysis check and that the no-repo case blocks analysis until a human connects a repository. It never names an alternative tool or states an explicit condition such as 'call before trigger_legacy_reanalysis' or 'use get_legacy_system for system metadata'.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the description's 'Read-only' tag is largely redundant. It does add value by disclosing the shape of the returned content (steps, connections, status, sprint/epic binding), but says nothing about pagination, error behavior for unknown IDs, or permissions.

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

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

A single dense sentence, front-loaded with the core action and followed by the return-field inventory; there is no filler.

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

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

There is no output schema, so the description must convey return contents, which it does via the enumerated fields. It is nearly complete for a simple one-parameter read, with only edge-case behavior (missing process, access limits) unexplained.

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

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

Schema coverage is 100% with a single required processId documented as a UUID, so the schema does the heavy lifting. The description adds no format, sourcing, or identifier-hierarchy guidance beyond the schema.

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

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

The description gives a specific verb and resource (full detail of one process model) and enumerates exactly what is returned: steps with name/type/role/duration, connections, status, and bound sprint/epic. This clearly separates it from list_processes and get_process_kpis without opening either schema.

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

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

The phrase 'one process model' combined with the required processId implies a fetch-by-id lookup, so usage is inferable. However, it never states when to choose this over list_processes, get_process_kpis, or list_process_insights, and gives no prerequisites or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description still adds real value by disclosing that values are computed from the live event stream (freshness semantics) and by enumerating what is returned in the absence of an output schema. The closing 'Read-only' merely restates the annotation, but that is a minor redundancy rather than a contradiction.

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

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

Front-loaded with the core purpose and the metric list, followed by two short qualifiers. Very little waste, though the trailing 'Read-only.' duplicates the annotation and could have been replaced with more useful information such as default window behaviour.

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 correctly takes on the job of listing the returned metrics, and it explains the data source. Remaining gaps — units/format of cycle-time percentiles, default time window, and whether a process needs to be mined/generated first — are modest but real for a metrics endpoint.

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 processId and the from/to fields are already documented; the description only echoes that the date window is optional and ISO-formatted. It does not clarify defaults, whether the window filters events or cases, or whether a missing window means all time, so it does not materially exceed the schema.

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

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

The description names the resource (a process), the source ('mined KPIs... computed from the live event stream'), and enumerates the metric families returned. It is clearly a metrics-read tool, but it never contrasts itself with near neighbours like get_sprint_metrics, list_process_insights, or run_process_insights, so an agent must 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?

Usage is only implied: '(Optimize)' and 'live event stream' hint at the mining context, and 'Optional from/to ISO date window' tells you the window is optional. There is no explicit statement of when to pick this over get_sprint_metrics or list_process_insights, and no prerequisites (e.g. does the process need mined event data first?).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations lack: the payload is a single record including full criteria and only the 5 most-recent PASS/FAIL events, which signals a bounded result set. It does not say what happens for an unknown or deleted 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?

One dense sentence covering the resource and return shape, followed by one short routing sentence. The verb and resource are front-loaded, and the '5 most-recent' cap plus the polymorphic target list are the kind of specifics that 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?

With no output schema, the description carries the return-value burden and does so well by naming the fields returned and the event cap. Missing only edge-case behavior (invalid/soft-deleted id) and whether the embedded criteria are full definitions versus summaries, which is partly implied by 'full criteria'.

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

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

Schema coverage is 100% and the single parameter is documented as a UUID, so the baseline would be 3. The description adds value by framing the id's provenance — it comes from stride.list_quality_gates — which the schema does not state, helping the agent obtain a valid value.

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 ('Fetch a single quality gate by id') and then enumerates exactly what the payload contains: criteria, status, gateType, polymorphic target binding, and recent evaluation events. This clearly separates it from sibling reads like list_quality_gates or run_quality_gate_check without requiring the reader to open the schema.

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

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

Explicitly routes id discovery to stride.list_quality_gates, giving the agent the prerequisite for a required parameter. It does not state the inverse (when not to use this, e.g. to actually evaluate a gate use run_quality_gate_check), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuine behavioral context with 'Soft-deleted releases read as not found,' which tells the agent how a deleted record manifests and prevents wasted retries. It stops short of describing auth requirements or the exact not-found response shape.

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: the core behavior with the returned field list front-loaded, then the soft-delete caveat. No filler, no restatement of the name or annotations.

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 usefully enumerates the returned fields (name, version, status, targetDate, description, storyIds, structured-notes flag), which is exactly the compensating detail needed for a single-param tool. Minor gap: no indication of error behavior for malformed UUIDs or a missing release.

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 sole parameter is documented in the schema as 'UUID of the release.' The description only reinforces that the id identifies a single release, adding little beyond the structured field, so the baseline 3 applies.

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

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

States a specific verb+resource ('Fetch a single release by id') and enumerates the fields returned, so the agent knows exactly what this tool produces. It implicitly separates itself from list_releases via 'single ... by id', but never names that sibling 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 'by id' — this is the lookup path when a release UUID is already known, as opposed to the bulk list. However, there is no explicit statement of when to prefer this over stride.list_releases or any exclusion for soft-deleted records beyond the not-found note.

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

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

Annotations already cover read-only/idempotent safety, and the description adds substantial non-obvious behavior: the 200-story inline cap, and that for COMPLETED sprints counts.stories/done and inline stories reflect only what remains after closing moved unfinished work out, with totals null when unrecorded. That is high-value disclosure beyond structured fields.

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

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

Front-loads purpose and return shape, then the sibling pointer, then the caveat about completed-sprint counts. Dense but every sentence conveys needed information; 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?

No output schema exists, and the description compensates by enumerating returned fields and clarifying count semantics and the inline-story cap. Nothing essential for correct invocation is missing besides the ID format nuance.

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 parameter (sprintId) with 0% schema description coverage, and the description says nothing about its expected format or where to obtain it. The parameter name is self-evident, so this is a minor but real gap rather than a fatal one.

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 (fetch) and resource (sprint) plus what is returned: name, status, goal, dates, and an inline array of compact stories. It explicitly distinguishes itself from stride.get_story, so an agent can pick it 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?

Explicitly routes deep story reads to stride.get_story ('Use stride.get_story for full story details') and explains the completed-sprint case. The alternative and the condition selecting it are both stated.

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

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

Annotations already declare read-only/idempotent, and the description goes well beyond them: it discloses the result-size budget rationale, the null semantics for score/forecast on completed sprints, that committedPts/completionPct/stories.total are null when unrecorded, and that capacity.perAssignee only counts stories still on the sprint after closing. This is exactly the kind of non-obvious behavior an agent cannot get from structured fields.

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

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

The payload is front-loaded in the first sentence, with the REST-endpoint scope note second and the completed-sprint caveats last. It is slightly dense and long for one paragraph, but each sentence carries non-redundant 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?

With no output schema, the description must carry return-value meaning, and it does name key fields and their null conditions. It falls short of describing the actual shape of nested results (burndown summary vs capacity vs scope-creep), which leaves some ambiguity for a composite metrics tool, but the critical edge cases are covered.

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

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

Only one parameter (sprintId) with 100% schema description coverage, so the schema already does the work. The description adds no format hints or constraints on the ID beyond what the schema states; its added meaning concerns return values rather than the parameter. Baseline 3 applies.

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

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

States a specific verb and resource ('Compact metrics snapshot for a sprint') and enumerates the contents (burndown summary, capacity totals, scope-creep, blocker count, health score), which implicitly separates it from get_sprint and get_sprint_test_health. It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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 line about full per-day burndown points, cycle-time and cumulative-flow staying on the REST endpoint is an effective 'when not to use this' signal for detail-hungry callers. However, there is no guidance on when to pick this over get_sprint or get_sprint_test_health, which are the closest in-domain alternatives.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely non-obvious semantics: case inclusion rules (story in sprint plus directly linked cases), 'most-recent executed result' as the state source, and the top-10 priority ordering. It stops short of noting cost/latency for an aggregate call, so not a full 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?

Front-loaded with purpose and scope, then the output breakdown, then sibling routing — no filler. The single long sentence with nested lists is dense but every clause carries 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?

No output schema exists, so the description must describe return content, and it does so precisely (metric families, ordering, cap of 10, coverage definition). Nothing an agent needs to call or interpret the result is missing.

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

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

Only one parameter (sprintId) with 100% schema coverage that already says 'Sprint UUID (stride.list_sprints)'. The description repeats that provenance without adding format or validation detail, so baseline 3 applies.

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

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

States a specific verb+resource (test health of ONE sprint) and enumerates the concrete outputs: case counts, pass/fail/blocked/skipped/never-ran breakdown, top-10 failed/blocked by priority, and story coverage. This is clearly distinguishable from siblings like get_sprint_metrics and get_test_run.

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 routes the agent: use this for test health, stride.get_sprint_metrics for delivery metrics (points, velocity), stride.get_test_run for a single run's results. The 'ONE sprint' scoping and required sprintId source (list_sprints) are stated up front.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by enumerating the returned fields (displayId, status, priority, points, labels, acceptance criteria, assignee, sprint/epic, related-entity counts) and by instructing the agent to cite the ticket key in replies.

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: purpose, return shape, then usage pointer — front-loaded and with no filler. The "ticket key in replies" instruction is short and actionable rather than padding.

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 correctly carries the burden by listing the fields returned, and single-parameter scope keeps things simple. The only softness is "related-entity counts", which stays vague about what is counted (comments? links? defects?).

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

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

Schema coverage is 100% and the schema already says ticket key is preferred. The description reinforces this with a concrete example ("ORB-526") and repeats the UUID alternative, adding a small amount of recognition value for an agent parsing user 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?

States a specific verb and resource ("Fetch a single Stride story") and names both accepted identifier forms. It is distinguishable from list_stories/search_stories by the word "single", but it never mentions the nearest sibling, stride.get_story_context, so an agent must infer the boundary 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?

Gives an explicit sequencing rule: "Use before stride.update_story_status so you know the current state." That is real when-to-use guidance with a named tool. It stops short of exclusions — nothing says when to prefer get_story_context or search_stories instead.

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