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

Beyond the annotations, the description explains that the tool returns an asynchronous jobs resource, requires read/write access, triggers a server-side action, and is not guaranteed idempotent. It also recommends `dry_run: true` for validation, which is useful behavioral context for a non-readOnly mutation.

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 definition is front-loaded with the core purpose and async behavior, then moves to prerequisites and alternatives. It is dense but mostly earns its length, though the closing note about executor preview formatting is somewhat meta and less useful at invocation time.

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

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

Given the output schema and rich annotations, the description covers the async workflow, permissions, alternative tool, and dry-run validation well. The main gap is the mismatched `requestBody.documentConfigurations` reference and the missing singular-vs-plural distinction from `branchDocuments`.

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 six parameters. The description adds some useful semantics about omitting target project/space to branch within the source, but it refers to `requestBody.documentConfigurations`, which does not match the input schema's direct `requestBody` properties. That inconsistency limits the added clarity.

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: creates a branched LiveDoc and returns an asynchronous `jobs` resource. It distinguishes itself from `copyDocument`, but it does not distinguish itself from the sibling `branchDocuments` plural tool, which is an important ambiguity given the near-identical name.

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

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

It explicitly states when to use `copyDocument` instead ('when branch lineage is not needed'), gives access prerequisites, and directs the agent to poll `getJob` for completion. This is clear guidance with an explicit alternative.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds the async job model, the required permission pair, the polling target, and a nuanced retry warning ("whether repeating it is safe, a no-op, or rejected depends on the specific action"). It also explains that dry_run returns a preview rather than executing — context no annotation provides.

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 the sibling alternative are front-loaded, and most sentences carry distinct information. The closing two sentences about how the executor surfaces the dry_run preview (plain text vs. structured content when an output schema is declared) are tooling meta-detail that adds length without helping an agent choose or call the tool.

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

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

With an output schema present, the description needn't document return values, and it still covers the async `jobs` handle and polling path. Combined with full schema coverage and annotations, an agent has everything needed: permissions, defaults for omitted targets, retry posture, and the single-document alternative.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by explaining the semantics of the nested `documentConfigurations` array — each entry supplies a source, may supply its own target, and "omitted targets stay with the source location." That default behavior is not stated in the schema's per-field 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?

States a specific verb and resource with scope: "Creates branches for multiple source LiveDocs and returns an asynchronous `jobs` resource." The plurality and the async job return are called out immediately, which is exactly what separates it from the singular `branchDocument` sibling.

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

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

Names the alternative explicitly ("Use `branchDocument` for one document"), states prerequisites (source read and target write permissions), and gives the follow-up workflow ("poll `getJob` for completion") plus a recommended dry_run-first procedure. When-to-use, when-not-to-use, and the next step are all 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?

Goes well beyond the annotations: annotations only say it is not read-only, is open-world, is not idempotent, and is not destructive. The description adds that contents are retained, that update permission is required, that it triggers a server-side action whose repeat behavior depends on the action, and that dry_run can preview the exact request.

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 purpose and follows with alternatives, behavioral caveats, and the dry-run tip. It is somewhat long, but each sentence contributes distinct routing or behavioral information and none of it is redundant with the 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 non-idempotent, open-world mutation with no output schema, the description covers everything an agent needs: lifecycle semantics, content retention, permission requirement, sibling alternatives, idempotency uncertainty, and a safe dry-run validation path.

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

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

Schema coverage is 100%, so the baseline is 3, and all three parameters are fully documented in the input schema. The description still adds procedural meaning for dry_run ('set `dry_run: true` first to validate the arguments and preview the exact request') and notes how the preview is returned, which is useful beyond the schema text.

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

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

States a specific verb and resource ('Closes one Collection') plus the key lifecycle effect ('changing its lifecycle state while retaining its contents'). That retention detail distinguishes it from deleteCollection and from the reopen/reuse siblings without requiring schema inspection.

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 alternatives: 'Use `reopenCollection` to make a closed Collection active again, or `reuseCollection` when continuing its contents as a new cycle.' The condition selecting each sibling is stated, and the permission prerequisite is included.

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

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

Beyond the annotations, it discloses that the source is left untouched, that this is a server-side action whose repeat behavior is action-dependent rather than guaranteed idempotent, and what dry_run actually returns. It stops short of stating permission/auth requirements or what happens when the target document name already exists — a real gap for a copy operation flagged destructiveHint=false.

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

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

Front-loaded with the core action and scoping before routing and dry-run advice, with no filler in the main sentences. The final sentence about structured content when an output schema is declared is meta-commentary about the executor rather than the tool, and could be trimmed.

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 nested-body mutation with full schema coverage, annotations, and an output schema, the description covers the operation, destination rules, sibling alternative, and idempotency stance. Missing only collision/overwrite semantics on the new document name, which an agent would otherwise have to guess.

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 baseline is 3; the description goes further by locating the target project, space, and new name inside `requestBody` and explaining the conditional semantics of omitting target project/space. It does not clarify `linkOriginalItemsWithRole` or `removeOutgoingLinks`, which remain schema-only.

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

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

The opening sentence names a specific verb (copies), a specific resource (one LiveDoc), the destination (target project and space), and the key invariant (source unchanged). It also explicitly differentiates itself from the `branchDocument` sibling, so an agent can pick between them 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?

It gives an explicit routing rule ('Use `branchDocument` when the copy must retain branch lineage'), a conditional rule for omitting target project/space, and a recommended pre-flight workflow (`dry_run: true`). When-to-use, when-not-to-use, and an alternative are all 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 declare readOnly=false, openWorld=true and idempotentHint=false, so the safety profile is known. The description still adds value beyond them by disclosing the permission requirement and fleshing out the non-idempotency caveat ("whether repeating it is safe, a no-op, or rejected depends on the specific action"). It stops short of saying what server-side side effects actually occur, 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?

Front-loaded with purpose, then prerequisites, alternatives, idempotency, and the dry-run tip in a sensible order. The closing sentence about how the executor surfaces the preview (plain text vs. structured content) is meta-tooling detail that is somewhat tangential and could be trimmed.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety hints. Given a mutation tool with nested request bodies, the description still supplies permission requirements, sibling routing, idempotency caveat, and a safe validation path — nothing essential for a correct first 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?

Schema coverage is 100%, so the baseline is 3; however the description adds the uniqueness constraint on project ID ("unique project ID") and frames `templateId` as optional template configuration, which is meaning beyond the raw field descriptions. The `dry_run` behavior is also explained, though largely echoing the schema description for that field.

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 and resource ("Creates a new Polarion project") and states the return ("returns the created project resource"). It actively distinguishes itself from nearby siblings by naming `markProject` as the alternative for registering existing repository data and `getProjectTemplates` for template lookup.

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

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

Gives explicit routing: call `getProjectTemplates` first when selecting a template, use `markProject` instead to register existing repository data. It also states the prerequisite (project creation permission) and recommends `dry_run: true` before the real call, so both when-to-use and when-not-to-use are 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?

Goes well beyond the annotations: it states the operation is irreversible and unrecoverable through the API, explains what `dry_run` actually skips (no request sent to Polarion), and describes how the preview is returned. The annotations only flag destructiveHint/idempotentHint; the description supplies the consequences an agent needs before mutating 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?

Front-loaded with the action and scope, then exclusions, then the danger warning, then the tip — a sensible order with little waste. The closing sentence about structured content is slightly conditional/boilerplate given this tool declares no output 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 bulk-delete with nested request body, it covers scope, alternatives, irreversibility, and a safe validation path — everything an agent needs to decide and call correctly, with payload shape left to the fully-described schema.

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

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

Schema coverage is 100%, so `dry_run` and `requestBody` are already documented; the description mostly reinforces that. It does add operational meaning by prescribing `dry_run` be used *first* as a validation step, which is sequencing guidance the schema does not convey.

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

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

States a specific verb and resource (deletes a list of Work Items) plus explicit scope (Global context, spans every project). It also names the sibling `deleteWorkItems` as the single-project variant, so an agent can distinguish it without opening either schema.

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

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

Gives an explicit routing rule (single project → use `deleteWorkItems`) and an explicit pre-call procedure (set `dry_run: true` first to validate and preview). Both when-to-use and a recommended safety sequence are 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 declare destructiveHint=true and openWorldHint=true, and the description reinforces this with the consequence ("cannot be recovered through the API") plus a concrete validation path via `dry_run` and how the preview is returned. The irreversibility statement is partly redundant with destructiveHint, but the dry_run semantics and return-shape note add 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-loaded with the action and cardinality, then the sibling alternative and the safety tip — good ordering and no filler. The closing sentence about structured content "when the tool declares an output schema" is meta-boilerplate that does not apply here (no output schema), slightly diluting an otherwise tight description.

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-record delete with full annotation coverage, complete schema docs and no output schema, the description covers scope, alternative, irreversibility and a dry-run safeguard. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so `projectId`, `workItemId`, `userId` and `dry_run` are already fully documented in the schema. The description only restates that the target is identified by ID and echoes the dry_run tip, adding little syntax or format detail beyond 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?

States a specific verb and resource ("Deletes the specified Work Item Approval") and immediately bounds the scope with "Cardinality: targets a single item by ID." It explicitly names the sibling `deleteApprovals` as the batch alternative, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit when-to-use (single item by ID) and when-to-use-the-alternative ("For the full collection or a batch, use `deleteApprovals` instead"). It also prescribes a safe workflow ("set `dry_run: true` first to validate the arguments"), leaving nothing 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 destructiveHint=true and idempotentHint=true, and the description goes beyond them by stating the effect is irreversible and unrecoverable through the API, plus a concrete dry-run preview path. The closing sentence about the executor returning preview as text/structured content is framework-level boilerplate rather than tool-specific behavior, 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?

Front-loaded with purpose and cardinality, then the alternative, then the safety tip — a sensible order. Slight waste in the final sentence, which explains executor plumbing that applies to every tool rather than this one.

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 what the agent most needs for a destructive batch mutation: scope, sibling alternative, irreversibility, and a validation escape hatch. Missing only permission requirements and partial-failure semantics (does one bad id abort the batch?), which matter for a batch delete but are not addressed.

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 projectId, workItemId, requestBody and dry_run are all documented in the schema itself. The description adds only the procedural hint to set dry_run first; it says nothing about how the requestBody array is matched (by id, by type) or what happens if an id is invalid. 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 ("Deletes a list of Work Item Approvals") and immediately clarifies cardinality ("full collection or a batch"), which is the exact axis that distinguishes it from the sibling deleteApproval. An agent can route between the two 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 names the alternative and the condition that selects it: "For a single item by ID, use `deleteApproval` instead." It also prescribes a safe-call workflow ("set `dry_run: true` first to validate the arguments"), leaving nothing 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 destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: the deletion is irreversible and unrecoverable through the API, and the dry_run preview is returned as normal text and as structured content when an output schema exists. That return-shape detail is useful since no output schema is declared.

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 labeled clauses (Cardinality, alternative, Effect, Tip) put the most decision-relevant facts first. The final sentence about text vs. structured preview is slightly long but still earns its place given the absent output 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 single-item delete with no output schema, the definition covers scope, the batch alternative, irreversibility, and a safe validation path. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so `projectId`, `collectionId`, and `dry_run` are already fully documented. The description adds only the high-level notion of ID targeting and the dry_run tip, which the schema already explains in more detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Deletes the specified Collection') and immediately scopes cardinality to a single item by ID. It explicitly names the sibling `deleteCollections` for the batch/full case, so an agent can distinguish it without reading 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 the batch case to `deleteCollections` and recommends running with `dry_run: true` first. It gives clear usage context but does not state prerequisites (e.g. permissions needed to delete, or whether the collection must be closed/empty first), so it stops short of the top score.

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 bar is lower; the description still adds real value by spelling out that removal is irreversible and unrecoverable through the API, plus how dry_run output is surfaced. It stops short of covering partial-batch failure behavior or permission requirements, which keeps it off 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 purpose, then cardinality, alternative, effect, and tip — a clean progressive structure. The trailing clause about the executor returning structured content 'when the tool declares an output schema' is conditional noise for a tool with no output 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?

Covers the essentials for a destructive nested-body batch delete on a tool with no output schema: scope, irreversibility, sibling routing, and a validation escape hatch. Missing only edge-case behavior such as what happens if some IDs in the batch are invalid.

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%, including a detailed dry_run definition and projectId scoping notes, so the schema carries the parameter burden. The description adds usage framing for dry_run but no new semantic detail about the nested requestBody data/id/type structure, 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 ('Deletes a list of Collections') and immediately clarifies cardinality (full collection or batch), which is exactly the ambiguity that distinguishes it from the singular deleteCollection sibling.

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

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

Explicitly routes the single-item case to `deleteCollection` instead, and gives actionable sequencing advice ('set dry_run: true first to validate the arguments'). Both when-to-use and which-alternative are stated 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?

Adds real context beyond annotations: the link-only (not resource) removal semantic, an explicit irreversibility warning, and a dry_run preview behavior path. The destructive irreversibility partly restates destructiveHint=true, but the 'resource not deleted' nuance and dry_run mechanics are genuine additions. Does not describe the response shape on a real (non-preview) call.

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

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

Front-loads the core action and scope in the first sentence, then alternatives and safety warnings. Every sentence is useful, though the trailing explanation of preview-as-text-vs-structured-content is somewhat verbose for the value it adds.

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

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

A destructive mutation with full schema coverage and strong annotations; the description covers what's removed, what isn't, alternatives, and a safety validation workflow. No output schema exists, so no return-value explanation is needed. Complete for correct invocation.

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

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

Schema coverage is 100%, so projectId, collectionId, relationshipId, requestBody, and dry_run are already documented in the schema. The description adds the dry_run preview behavior but otherwise restates what the schema provides. 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 (Removes) and resource (named relationship from one Collection) with clear scope. Explicitly clarifies that the related resource itself is not deleted, distinguishing the effect from a resource deletion. Routes cleanly against sibling get/post/patch relationship 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?

Names all three alternatives explicitly: getCollectionsRelationship to read, postCollectionsRelationships to add, patchCollectionsRelationships to replace. Also advises dry_run:true as a validation step first. The selection logic is fully 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is known. The description adds genuinely new context beyond that: the exact consequence ("irreversible — data removed or overwritten by this call cannot be recovered through the API") and how dry_run behaves (preview returned as normal text and structured content, not sent to Polarion). It stops short of describing cascade behavior for child parts 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?

The irreversible-effect warning and the dry_run tip are front-loaded and earn their place. The closing sentence about the executor returning previews "as structured content when the tool declares an output schema" is meta-commentary that does little work here, since no output schema is declared for this 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 destructive bulk-delete with a nested request body and no output schema, the description covers the two things an agent most needs: irreversibility and a validation path. It omits whether deleting a part cascades to children, how missing/unknown IDs are handled, and required permissions, which are meaningful gaps for a destructive operation but not blocking.

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 every parameter — including the nested requestBody.data array — is already documented in the schema. The description reinforces that the body is a list of Document Part IDs and contextualizes dry_run, but adds no format, limit, or edge-case detail beyond 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?

States a specific verb and resource ("Deletes a list of Document Parts") that an agent can clearly separate from getDocumentParts, postDocumentParts, moveDocumentParts, and overwriteDocumentParts. It does not explicitly name which sibling is the non-destructive alternative, so it stops 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?

The description gives a useful pre-flight recommendation ("set dry_run: true first to validate the arguments"), which is usage guidance for safe invocation. However, it never says when to choose this tool over overwriteDocumentParts, moveDocumentParts, or deletePage — the destructive-vs-modifying distinction among siblings 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 destructiveHint=true and idempotentHint=true, yet the description adds the crucial fact that removal is irreversible and unrecoverable through the API, plus how the dry-run preview is returned. That is genuine context beyond structured fields rather than restatement.

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 cardinality, then alternatives, then risk, then the dry-run tip — a sensible priority order. The trailing sentence explaining preview delivery formats is slightly verbose for the value it adds.

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, 6-required-parameter mutation with no output schema, the definition covers cardinality, alternative tool, irreversibility, and a safe validation path. It stops short of mentioning permission/scoping requirements or what happens to the counterpart work item, but the essentials are present.

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 every parameter carries its own description, so the schema does the heavy lifting. The description only echoes the `dry_run` parameter, which the schema already documents in more 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 and resource ('Deletes the specified Externally Linked Work Item') and immediately disambiguates the singular form from the plural batch sibling by name. An agent can distinguish this from deleteExternallyLinkedWorkItems 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 routes the batch/collection case to `deleteExternallyLinkedWorkItems` and recommends a `dry_run: true` validation pass before mutating. It does not, however, contrast this against the similarly named `deleteLinkedWorkItem` sibling in the same family, which is the remaining ambiguity.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description's main job is added context — which it delivers by spelling out that removals are unrecoverable through the API, and by describing exactly what the dry_run preview returns (redacted Authorization header, binary payloads summarized). It does not describe batching limits or partial-failure behavior, so it falls short of 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 cardinality and sibling routing, which is the right ordering for a delete tool. The closing sentence about the executor returning preview as text and structured content is meta-detail that earns its place less than the rest, keeping it from a 5.

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 explaining what the dry_run preview yields. For a destructive batch delete with fully described parameters, the remaining gap is what a successful real deletion returns — minor but real, so not a 5.

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 projectId, workItemId, requestBody, and dry_run are all documented in the schema itself; the description repeats only the dry_run tip. The nested requestBody shape (id/type array, single enum value) is left entirely to the schema. Baseline 3 applies when the schema carries the parameter burden.

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 ('Deletes a list of Externally Linked Work Items') plus the scope ('targets the full collection or a batch'), and explicitly names the singular sibling `deleteExternallyLinkedWorkItem` for the single-item case. An agent can distinguish it from the many other delete* siblings 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 an explicit routing rule ('For a single item by ID, use `deleteExternallyLinkedWorkItem` instead') and a recommended operating procedure ('set `dry_run: true` first to validate the arguments and preview the exact request'). Both when-to-use and when-not-to-use are present, not inferred.

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 mostly pre-supplied. The description still adds real value by spelling out that the effect is irreversible and unrecoverable through the API, and by describing the dry_run preview mechanism — but it never says what the delete actually removes (the whole field definition, its values, existing data on work items?), which is the key unknown for a destructive call.

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

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

Front-loads the action and scope, then the alternative, then the consequence, then the tip — a sensible ordering with little waste. The closing sentence about previews being returned as text or structured content is generic executor boilerplate rather than tool-specific information, so it is the one sentence that does not fully earn 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?

No output schema exists, but for a delete tool the essential context (scope, alternative, irreversibility, dry_run) is present, and destructiveHint covers risk signaling. The remaining gap is that `resourceType` is described only as "The Resource Type," so the agent gets no help identifying the target field from the description either.

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 baseline is 3; the description pushes above it by explaining the practical behavior of `dry_run` (validation, preview, redacted auth header, no request sent). However it adds nothing about how `resourceType`/`targetType` identify which global field is deleted, which is the parameter interpretation that actually matters here.

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 ("Deletes the specified Custom Field configuration") plus the scope ("Global context") in the first two sentences. It explicitly names the sibling `deleteProjectCustomFields` as the narrower alternative, so an agent can discriminate between the two without opening either schema.

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

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

Gives an explicit when-not rule: "To act on a single project, use `deleteProjectCustomFields` instead," along with the selection condition (global vs. single-project scope). It also prescribes a safe practice (dry_run first), covering both routing and procedure.

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, but the description adds the concrete consequence: "irreversible — data removed or overwritten by this call cannot be recovered through the API." It also explains what dry_run returns and how it is surfaced (text plus structured content). It stops short of stating permission/auth requirements, keeping it just under 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 action and scope, then the alternative, then the risk warning — a sound ordering. The trailing sentence about how the executor returns the preview ("as normal text, and as structured content when the tool declares an output schema") is generic executor boilerplate that is only loosely tied to this 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 destructive, no-output-schema delete tool, the definition covers scope, the sibling alternative, irreversibility, and a safe dry-run path. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, with dry_run, enumName, targetType and enumContext all documented in the schema itself, so the baseline is 3. The description's only additional parameter guidance is the dry_run workflow tip, which largely restates the schema's dry_run description.

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

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

States a specific verb and resource ("Deletes the specified Enumeration") plus the scope ("Global context. Scope: spans every project"). It explicitly names the sibling it is not (deleteProjectEnumeration), so an agent can distinguish it without opening either schema.

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

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

Gives explicit routing: use this for the global context, use `deleteProjectEnumeration` for a single project. It also prescribes a safe workflow ("set dry_run: true first to validate the arguments and preview"), which is exactly the when-to-use guidance a destructive tool needs.

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 bar is lower, but the description still adds permission requirements, an explicit irreversibility warning ('cannot be recovered through the API'), and the exact behavior of dry_run (validates, redacts the Authorization header, summarizes binary payloads, returns preview as text and structured content). That is material context absent from 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-loaded with the action and scope, then permission, verification steps, irreversibility, and the dry_run tip in a sensible order. The closing sentence about structured content versus normal text is slightly meta and reads as filler for a tool with no output 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?

Covers permission model, reversibility, verification workflow, and safe dry-run validation — more than enough for a destructive three-parameter tool whose safety profile is already in annotations. The one gap is the request body: the schema describes it only as 'No Content', and the description does not explain the id/type payload either, leaving the actual deletion target under-specified.

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 dry_run is already fully documented in the schema, so the description's tip largely restates it. It adds no interpretation of typeId or of the requestBody shape (array of objects with id and type: license_slots), which is where an agent would most benefit from guidance. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Deletes specified license slots') plus the scope ('server-wide administrative change'), which separates it from the many page/document/work-item delete siblings. It also names the read counterparts (getLicenseSlots, getLicense) so the agent can place it in the right family of license 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?

Gives an explicit precondition ('requiring license administration permission'), explicit pre-steps ('Read current assignments with getLicenseSlots and capacity with getLicense before removal'), and recommends an alternative execution mode ('set dry_run: true first') before committing. There is essentially no inference left about when to call this versus a read 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?

Beyond the destructive annotation, the description explains exactly what is removed, what is not affected, and that the operation is irreversible with no API recovery path. The dry_run preview tip adds actionable safety guidance for a destructive operation.

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

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

The description is front-loaded with the core action and scope, and most sentences earn their place. The Java API parenthetical and detailed preview-format sentence are slightly more verbose than needed for an agent selecting and invoking the tool.

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

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

For a destructive single-item delete with full schema coverage and no output schema, the description covers purpose, exclusions, alternative tool for batch use, irreversibility, and dry_run validation. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so parameter meaning is already fully documented in the schema. The description clarifies cardinality but does not add per-parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: deletes direct outgoing links to Work Items. It distinguishes the tool from related siblings by excluding external links and backlinks and by naming deleteLinkedWorkItems for batch or full-collection deletion.

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

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

It explicitly states the scope: single-item deletion by ID. It also gives exclusions (external links and backlinks) and a concrete alternative for batch/full collection deletion via deleteLinkedWorkItems.

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 destructive=true and idempotent=true, and the description adds meaningful context beyond that: the deletion is irreversible and cannot be recovered through the API, its scope is limited to direct outgoing links, and dry_run returns a preview without sending the request.

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 and efficient: it states what is deleted, what is excluded, the batch alternative, the irreversible effect, and the dry_run tip. The parenthetical Java API reference and the executor output note are slightly extraneous but do not obscure the main guidance.

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

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

For a destructive batch-delete tool with no output schema, the definition covers scope, irreversibility, alternative tooling, and dry_run preview behavior. It does not describe success response behavior or partial-batch failure semantics, but the schema is fully described and the description is otherwise sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents projectId, workItemId, requestBody, and dry_run in detail. The description adds cardinality and dry_run guidance, but does not materially explain the nested requestBody structure beyond what the schema provides.

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

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

The description states a specific verb and resource: deletes direct outgoing links to other Work Items. It clearly limits scope by excluding external links and backlinks, and distinguishes the batch/full-collection behavior from the single-item sibling deleteLinkedWorkItem.

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

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

It explicitly routes single-item deletion to deleteLinkedWorkItem and states what this tool does not handle (external links and backlinks). The dry_run tip gives concrete guidance for validating before an irreversible batch deletion.

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

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

With annotations already declaring destructiveHint/readOnlyHint, the description adds valuable behavior beyond them: only the link is removed and the remote OSLC artifact is untouched, the operation is irreversible, and `dry_run` previews the request. The closing sentence about structured content is generic boilerplate that is slightly at odds with the tool declaring no output schema.

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

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

Front-loaded with the action and scope, then alternatives, then safety. Every sentence mostly earns its place, though the final explanation of normal vs. structured dry-run output is extraneous for a tool that declares no output 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?

Given this is a destructive mutation with open-world side effects and no output schema, the description supplies exactly what matters: what is deleted, what is not, how to validate safely, and which sibling tools handle adjacent operations.

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 baseline is 3. The description adds genuine meaning by specifying that `requestBody.data` entries are link IDs exactly as returned by `getOslcResources`, which is not obvious from the bare nested 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 ('Removes one or more OSLC links from a Work Item') and immediately scopes the removal to link IDs returned by `getOslcResources`. It distinguishes itself from `postOslcResources` and `deleteLinkedWorkItems` without requiring the agent to open any schema.

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

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

Explicitly routes the agent: use this tool for OSLC link removal, use `postOslcResources` to add links, and use `deleteLinkedWorkItems` for Polarion-internal links. It also prescribes a safe validation pattern with `dry_run: true` before executing.

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 destructive=true, readOnly=false, and idempotent=true, but the description goes further by stating the deletion is permanent, cannot be undone through the API, and requires page deletion permission. It also describes the dry-run preview behavior, including structured output when an output schema exists.

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

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

The core message is front-loaded, but the text repeats the irreversibility idea twice ('cannot be undone' and 'irreversible — data removed or overwritten...') and explains dry_run preview more than once. It is useful but not maximally tight.

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 covers the critical context for a destructive mutation: permanence, permission requirement, alternative editing tool, and a dry-run validation path. Nothing essential for safe invocation 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?

Schema coverage is 100%, so the schema already explains `projectId`, `spaceId`, `pageName`, and `dry_run` in detail; baseline is 3. The description adds some value by framing `dry_run` as a validation/preview step and by surfacing the permission requirement, but it does not meaningfully expand the individual parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Permanently deletes one Rich Page and its content.' It scopes the action to a single page and immediately distinguishes it from editing via `patchRichPage`, so an agent can separate it from sibling delete/patch page tools.

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

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

It explicitly says to use `dry_run` to preview, `patchRichPage` to edit without deleting, and notes the required page deletion permission. These are concrete when-to-use and when-to-choose-an-alternative signals rather than implied guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds value by spelling out that the effect is irreversible and unrecoverable via the API, plus how dry_run previews the request (header redaction, binary summarization). It does not mention permissions or failure behavior for a nonexistent attachment, but it adds real context beyond the annotations.

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

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

The action and irreversibility warning are correctly front-loaded, but the closing sentence about structured content 'when the tool declares an output schema' is speculative filler given this tool has no output schema, and it dilutes an otherwise tight definition.

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, 5-parameter delete with no output schema, the description covers destruction and the dry-run escape hatch, which is the core need. It omits what happens when the attachment does not exist, required permission scope, and any sibling routing, leaving identifiable gaps.

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

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

Schema description coverage is 100%, so all five parameters, including dry_run, are fully documented in the schema. The description restates dry_run's purpose but contributes no syntax, defaults, or ID-format guidance beyond what the schema already provides; 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 ('Deletes the specified Page Attachment'), which is distinguishable from siblings like deletePage, deleteTestRecordAttachment, or deleteDocumentParts. It does not explicitly contrast with patchPageAttachment or the bulk attachment deletes, but the resource is named precisely enough to select 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 dry_run tip gives practical guidance on how to invoke it safely, but there is no statement of when to use this versus patchPageAttachment, deleteTestRecordAttachment, or the plural attachment deletes, and no prerequisites or permission notes. Usage is implied rather than routed.

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 earns credit by adding substance beyond them: it spells out that the effect is irreversible and cannot be recovered through the API, and it documents the dry-run preview channel (plain text vs. structured content). It does not say what scope is affected (all links under one relationship name? only listed entries?), 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?

Front-loaded with the action, then the irreversibility warning, then the dry-run tip — good ordering with no filler sentences. The closing clause about the executor returning structured content "when the tool declares an output schema" is meta-noise for a tool with no output schema and partially restates the dry_run schema description.

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 mutation with full annotation coverage and a 100%-documented schema, the description supplies the two things the structured fields can't: irreversibility and a safe validation path. The main remaining gap is not explaining the shape/semantics of the `data` array that carries the IDs to remove.

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

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

Schema description coverage is 100%, so the baseline is 3; the description's only parameter-related content is the dry_run tip, which the schema already documents in more detail. It adds no clarification of the nested `requestBody.data[].id` / `.type` entries that actually determine which relationships are deleted.

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: "Deletes a list of Page Relationships." That is clearly distinct from the read/write relationship siblings (getPageRelationships, postPageRelationships, patchPageRelationships) and from deletePage, though the description never explicitly names those alternatives to reinforce the boundary.

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

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

It gives procedural advice (set `dry_run: true` first to validate arguments) which is genuine usage guidance, but it never says when to choose this tool over deletePage/deleteDocumentParts or what prerequisites must hold before deleting relationships. Usage is implied by the name 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds meaningful context beyond them by stating that deletion is irreversible and unrecoverable through the API, and by explaining the dry_run preview behavior.

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

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

The description is front-loaded with the core action and scope, and most sentences earn their place. The final sentence about executor preview output is somewhat verbose but still relevant to dry_run behavior.

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

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

For a destructive single-item delete tool with full schema coverage and no output schema, the description provides the necessary scope, alternative, irreversibility warning, and dry_run guidance. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, and the schema already documents planId, projectId, and dry_run thoroughly. The description reinforces the dry_run workflow but adds little technical detail beyond what the schema provides.

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

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

The description uses a specific verb and resource: "Deletes the specified Plan." It also explicitly scopes the operation to a single item by ID and distinguishes it from the batch sibling deletePlans.

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

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

It states exactly when to use this tool versus deletePlans for full-collection or batch deletion. It also recommends setting dry_run: true first to validate and preview the request.

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, but the description adds material context beyond them: the effect is irreversible and removed or overwritten data cannot be recovered through the API. It also explains what dry_run returns in preview mode, which is useful behavioral detail.

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

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

The description is front-loaded with the core action, then moves efficiently through alternatives, destructive effect, and the dry_run tip. Each sentence contributes useful routing or safety information without excessive 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 destructive relationship-deletion tool with a nested request body and no output schema, the description covers the critical gaps: what is removed, what is preserved, alternative operations, irreversibility, and a safe dry-run path. The remaining structural details are fully handled by the input schema.

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

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

Schema description coverage is 100%, so the parameter semantics are already fully documented in the schema. The description adds some contextual meaning around dry_run and the relationship name, but it does not materially expand on the nested requestBody structure beyond what the schema already provides.

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

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

The description states a specific verb and resource: it removes a named relationship from a Plan while explicitly preserving the related resource. It also names the sibling tools for reading, adding, and replacing relationships, so an agent can distinguish it from adjacent operations 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?

It explicitly routes the agent: use getPlanRelationship to read current links, postPlanRelationships to add, patchPlanRelationships to replace, and this tool to delete. It further advises setting dry_run first to validate arguments, which is actionable usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still adds value beyond them: it spells out that the effect is irreversible and unrecoverable through the API, and explains exactly what dry_run returns (redacted Authorization header, byte-length-summarized binaries) and in which channel (text vs. structured content). Minor gap: no mention of permission requirements or side effects on related plans/relationships.

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 sibling-routing rule are front-loaded, and each labeled clause (Cardinality, Effect, Tip) carries distinct information. It is slightly padded — the explanation of how the executor returns the preview is longer than an agent strictly needs — but nothing is redundant.

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

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

For a destructive batch mutation with no output schema, the description covers the essentials: irreversibility, the single-vs-batch routing, and the dry-run escape hatch. What remains unstated is whether deletion cascades to dependent records (plan relationships, test records) and what permissions are needed, which is the main residual 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%, so the schema already documents projectId, dry_run, and requestBody, and the description's dry_run advice only restates that. The nested requestBody ('The Plan(s) body.') is the least documented element and the description adds nothing about its `data[].id`/`type: plans` structure, 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 ('Deletes a list of Plans') plus the cardinality semantics ('targets the full collection or a batch'), and names the sibling to use for the single-item case (`deletePlan`). An agent can distinguish this from deletePlan without opening either schema.

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

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

Gives an explicit routing rule ('For a single item by ID, use `deletePlan` instead') and a recommended pre-flight procedure (set `dry_run: true` first to validate and preview). Both when-to-use and which-alternative are stated outright, not 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 flag destructiveHint=true, so the safety profile is partly structured; the description nonetheless adds genuinely new context: the required 'project deletion permission' and the dry_run output behavior (preview returned as normal text and as structured content). Minor redundancy — irreversibility is asserted twice — keeps it just below top marks.

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 lead sentence is front-loaded and strong, but the text repeats irreversibility in two adjacent sentences and closes with generic executor boilerplate about structured content. Roughly half of the length is restatement rather than new 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 two-parameter destructive tool with full annotation coverage and an output schema, this is complete: it covers destructiveness, permission prerequisites, the safety valve (dry_run), and the non-destructive alternative. 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 description coverage is 100% and the dry_run parameter is documented in detail there, so the baseline is 3. The description does add one framing detail the schema lacks: the tip to set `dry_run: true` first as a validation workflow step, which gives the parameter operational meaning in the description itself.

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 deletes a Polarion project and its project data, including contained resources'), including the cascade scope of the deletion. It also names the sibling it is not — `unmarkProject` when data should remain — so an agent can distinguish 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 between options: use `dry_run` to preview/validate, and use `unmarkProject` instead when the project data must stay in the repository. Both the when-to-use and the key when-not-to-use alternative are stated outright.

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 beyond the annotations by stating the effect is irreversible and that removed/overwritten data cannot be recovered through the API, and by describing what dry_run returns (preview as text, and as structured content when an output schema is declared). Annotations already flag destructiveHint/idempotentHint, so this is additive rather than contradictory.

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 scope, followed by the alternative, the danger, and the dry_run tip in a predictable order. The final sentence about executor output is somewhat verbose for the value it carries, but nothing is 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?

A destructive, no-output-schema mutation tool needs scope, danger, and a safe-preview path — all present. Minor gap: the description does not explain what 'resourceType'/'targetType' select, though the schema covers them at 100%.

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 all four parameters are already documented, and the description mostly restates the projectId scoping and the dry_run purpose rather than adding new semantics. It does clarify the dry_run return channel, which is mildly additive, but resourceType and targetType meaning comes entirely from 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+resource ('Deletes the specified Custom Field configuration') scoped explicitly to the Project context, which separates it from the many deleteDelete* siblings and from its nearest lookalike, deleteGlobalCustomFields. 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?

Explicitly names the alternative (`deleteGlobalCustomFields`) and the condition that selects it ('to act across all projects'), plus the prerequisite of a project ID. It does not mention when to prefer patchCustomField over deletion, but the cross-scope routing is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substance beyond them: it states the loss is irreversible and not recoverable through the API, and it explains the dry_run path including how the preview is returned (plain text and structured content when an output schema exists). Only permission/authorization requirements are left unspecified.

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 scope, then the alternative, then the irreversibility warning, then the dry_run tip — a logical order with no filler. The final sentence about text versus structured preview output is slightly over-explained for a delete 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 5-parameter destructive mutation with no output schema, the description covers scope, alternative routing, irreversibility, and safe validation. It leaves out what happens on failure (e.g. nonexistent enumeration) and any permission prerequisites, which would be the remaining gaps.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents projectId, enumName, enumContext, and targetType. The description adds meaning the schema doesn't: that projectId is a scope requirement, and that the way to validate parameters safely is to set dry_run first, which is a usage-level insight rather than a restatement.

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 (deletes the specified Enumeration) plus the exact scope (Project context, requires a project ID). It explicitly distinguishes itself from the sibling deleteGlobalEnumeration, so an agent can route correctly 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?

Names the alternative tool (`deleteGlobalEnumeration`) and the condition that selects it (acting across all projects), and recommends a validation-first workflow via `dry_run: true`. When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already declare destructiveHint/idempotentHint, but the description adds material context beyond them: explicit irreversibility ("cannot be recovered through the API") and the exact semantics of the dry_run preview, including how the response is delivered. That is genuinely actionable behavior disclosure, not repetition.

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?

Deletion scope and the batch alternative are front-loaded, which is the right ordering for a destructive tool. The final clause about structured content vs. normal text is somewhat meta and less essential, but the rest is dense and waste-free.

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 single-item delete with no output schema, the description covers target scope, irreversibility, the batch alternative, and a safe validation path — everything an agent needs to call it correctly or avoid calling 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%, so projectId and dry_run are already well documented in the schema; the description only repeats the dry_run intent. Baseline 3 applies since the schema carries the parameter burden.

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 ("Deletes the specified Test Parameter Definition for the specified Project") and immediately contrasts with the sibling `deleteProjectTestParameterDefinitions`, so the agent can distinguish single-item from batch deletion without inspecting either schema.

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

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

Gives explicit routing guidance ("targets a single item by ID. For the full collection or a batch, use `deleteProjectTestParameterDefinitions` instead") plus a recommended pre-flight workflow ("set `dry_run: true` first to validate the arguments"). Both when-to-use and the alternative are named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value on top by spelling out that the effect is irreversible and unrecoverable through the API. It also describes what dry_run actually returns (redacted Authorization header, binary summarized by byte length, text vs structured output). It does not cover permission requirements or partial-failure behavior for a batch, which keeps it below 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 purpose, then cardinality, alternative, effect, and tip in a logical order. Slightly verbose in the final sentence about preview output, but every sentence carries usable 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 a mutation tool with no output schema, the description covers the destructive semantics, the sibling alternative, and the dry_run safety path. Remaining gaps are edge-case behaviors (what happens to nonexistent or referenced IDs, batch atomicity) rather than anything required to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents projectId, requestBody, and dry_run thoroughly. The description adds meaning beyond the schema by explaining the executor's preview return format for dry_run rather than just restating the flag.

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 (Deletes), resource (Test Parameter Definitions), scope (specified Project), and cardinality (full collection or batch). It explicitly distinguishes itself from the singular sibling `deleteProjectTestParameterDefinition`, so an agent can disambiguate 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?

Names the alternative and the exact condition that selects it ('For a single item by ID, use `deleteProjectTestParameterDefinition` instead') and recommends a dry_run-first workflow. It leaves little to inference about when this tool is the right choice.

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, and the description adds genuinely new context: irreversibility ('cannot be recovered through the API') and the dry-run preview path. It slightly repeats the dry_run mechanics that the schema already documents, and does not describe the response of an actual (non-preview) 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?

Front-loaded with the scope distinction, then alternatives, then the irreversible warning — good ordering with no filler sentences. The closing note about structured content appearing 'when the tool declares an output schema' is meta-commentary of marginal use to a caller.

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 six-parameter mutation with no output schema, the description covers the safety profile, the alternative paths, and a validation mechanism. The only gap is what a successful real deletion returns, which is not addressed anywhere.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by framing `iteration` as the specific repeated execution being targeted and by explaining what the dry-run preview yields. Other parameters (projectId, testCaseProjectId) are left entirely to 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 ('Deletes one Test Record execution in a Test Run iteration') and immediately scopes it against the confusable neighbor ('not the Test Case definition'). Among many delete* siblings, an agent can tell exactly which entity this removes.

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 `getTestRecords` to identify the record, use `patchTestRecord` when only values should change, and call this only when the execution itself must be removed. It also prescribes a safe pre-flight (`dry_run: true`) before committing.

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, readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description adds that deletion is irreversible and that dry_run returns a preview as text and structured content, which is meaningful context beyond the annotations.

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

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

The description is front-loaded with the action and scope, and each following sentence adds useful detail: batch alternative, irreversibility, and dry-run preview. No sentence 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 mutation with full schema coverage and no output schema, the description supplies the missing operational context: irreversibility, the batch alternative, and dry-run preview behavior. An agent has enough information 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% for all 7 parameters, so the schema already explains each parameter's meaning. The description reinforces single-item ID targeting and the dry_run preview, but adds little parameter semantics beyond what the schema provides, so the 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: 'Deletes the specified Test Record Attachment.' It then clarifies cardinality ('targets a single item by ID') and names the batch sibling deleteTestRecordAttachments, which distinguishes it cleanly from alternatives.

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 full-collection or batch deletions to deleteTestRecordAttachments and recommends setting dry_run: true first to validate and preview the request. That gives both the alternative and the safer usage pattern for a destructive call.

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, but the description adds that the effect is irreversible and that data cannot be recovered through the API. It also explains the dry_run preview behavior, including how the preview is returned. The final clause about structured content when an output schema is declared is slightly confusing here because this tool has no output schema.

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

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

The description is short and front-loaded: purpose, cardinality, alternative tool, irreversibility, then the dry_run tip. The only minor inefficiency is the trailing detail about structured content when the tool declares an output schema, which is not applicable here and could distract.

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 batch-delete tool with rich annotations and a fully described schema, the description covers the critical gaps: cardinality, the sibling alternative, irreversibility, and safe preview via dry_run. It does not describe the actual success response, but annotations and the dry_run advice reduce the need for that, and 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 description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining why and how to use `dry_run: true` for this destructive operation and by clarifying that the target is a full collection or batch, which gives added meaning to the nested requestBody structure.

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 ('Deletes a list of Test Record Attachments') and immediately distinguishes the batch/collection cardinality from the single-item sibling. An agent can tell it apart from deleteTestRecordAttachment 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 names the alternative tool and the condition that selects it ('For a single item by ID, use `deleteTestRecordAttachment` instead'). It also recommends a safe first invocation via `dry_run: true`, which gives concrete usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substance: irreversibility is spelled out ('cannot be recovered through the API'), and the dry_run preview path is explained including how the executor surfaces the preview. It does not state what a successful delete returns, which keeps it below 5.

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

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

Front-loaded with scope and effect, then alternatives, then the dry_run tip — logical ordering with little filler. The trailing sentence about the executor returning preview as text and structured content is somewhat meta and could be trimmed.

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 seven-parameter delete with no output schema, the essential context is present: what is destroyed, that it is unrecoverable, which alternatives to prefer, and how to preview safely. The only gap is the post-success response shape, which is minor for a delete.

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 all seven parameters are documented in the schema, so the baseline is 3. The description only touches dry_run, and even that largely restates the schema's own dry_run description; none of the six required identifiers (iteration, testCaseProjectId, testParamId) get added meaning in prose.

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 ('Removes one parameter value from a Test Record execution') and immediately scopes it negatively ('without deleting the record or Test Case'), which disambiguates it from deleteTestRecord. An agent can distinguish it from the many sibling delete* tools without inspecting schemas.

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

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

Explicitly names two siblings and the role each plays: getTestRecordTestParameters to inspect, patchTestRecordTestParameters to modify instead of remove. Combined with the dry_run-first tip, the agent has a concrete decision path rather than inferred usage.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description earns credit beyond that by spelling out that the effect is irreversible and unrecoverable through the API. It further discloses the dry_run preview behavior and how that preview is returned (text, and structured content when an output schema is declared).

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 verb, scope, and the sibling split, and nearly every sentence carries information. The closing sentence about the executor returning structured content is partly boilerplate here, since this tool declares no output schema, which makes that conditional clause dead weight.

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 single-item delete with no output schema and full parameter documentation, the description covers target, alternative, irreversibility, and a safe pre-flight path. 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 description coverage is 100%, so the baseline is 3 and the schema already explains projectId, testRunId, and dry_run. The description adds meaning to dry_run by framing it as a validate-and-preview safety step rather than just a boolean, though it repeats schema content about Authorization redaction and binary summarization.

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 ('Deletes the specified Test Run'), then pins scope with 'Cardinality: targets a single item by ID'. It explicitly names the sibling it is not (deleteTestRuns) for collection/batch work, so an agent can distinguish it 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 an explicit alternative with its selection condition: use `deleteTestRuns` for the full collection or a batch. It also prescribes a concrete safe workflow (set `dry_run: true` first to validate and preview), leaving nothing to inference about how to approach this call.

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, and the description reinforces this with a plain statement that the effect is irreversible and unrecoverable through the API. It also explains the dry-run preview behavior and how the preview is surfaced (text vs. structured content), which annotations do not convey; it stops short of mentioning required permissions or failure modes.

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 cardinality, followed by the alternative, the destructive warning, and the dry-run tip — every sentence carries operational value. The closing sentence about text vs. structured preview is slightly meta and could be trimmed.

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-item destructive delete with no output schema, the description covers identity, scope, irreversibility, the batch alternative, and a validation path — enough for correct invocation. Minor gaps remain around permission requirements and what the response contains on success.

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 (including `dry_run`) are already fully documented in the schema, which sets the baseline at 3. The description only echoes the `dry_run` semantics rather than adding new meaning about `projectId`, `testRunId`, or `attachmentId`.

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 ('Deletes the specified Test Run Attachment') and immediately clarifies cardinality ('targets a single item by ID'), which is exactly the axis an agent needs to distinguish it from `deleteTestRunAttachments`.

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 one item, use `deleteTestRunAttachments` for the full collection or a batch. It also gives a concrete pre-flight procedure (set `dry_run: true` first), so both when-to-use and how-to-verify are 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. The description still earns credit by spelling out the consequence in plain language ('irreversible — data removed or overwritten cannot be recovered through the API') and describing the dry-run preview's return behavior (normal text, plus structured content when an output schema is declared). It does not cover permissions/auth requirements or partial-failure behavior on a batch, which keeps it below 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 operation and cardinality, then the alternative, then the risk, then the tip — a sensible order with no filler. The dry-run sentence restates what the `dry_run` schema property already says in full, which is the one redundant passage.

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-body mutation with full annotation and schema coverage and no output schema, the description supplies what the structured fields do not: irreversibility, batch-vs-single routing, and the preview workflow. Only auth/permission prerequisites and batch partial-failure semantics are missing.

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

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

Schema description coverage is 100%, so the schema already documents projectId, testRunId, dry_run and the requestBody envelope. The description only reinforces `dry_run` and adds no meaning for the nested `data` array or the `testrun_attachments` type discriminator, 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 ('Deletes a list of Test Run Attachments') and immediately clarifies cardinality ('full collection or a batch'), which is the exact axis that distinguishes it from the singular sibling. It names `deleteTestRunAttachment` as the alternative for single-ID deletes, so an agent can discriminate 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?

Explicit routing: use this tool for a batch/full-collection delete, use `deleteTestRunAttachment` for a single item by ID. It also gives a recommended pre-flight step (`dry_run: true` to validate and preview), which is actionable usage guidance rather than implied context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable context: deletion is irreversible and data cannot be recovered through the API. It also explains the dry-run preview behavior, though it does not clarify what 'full collection' means operationally (e.g., empty data array) or any 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?

The description is front-loaded with the core action and alternative, then layers on irreversibility and dry-run guidance. The final sentence about executor return format ('normal text ... structured content when the tool declares an output schema') is extraneous since no output schema exists and does not help an agent call the tool.

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

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

Given rich annotations, full schema coverage, and no output schema, the description covers the essential behavioral and usage context. It could be more complete by clarifying how to target the full collection versus a batch, or whether related attachments are affected, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents `projectId`, `dry_run`, and `requestBody` in detail. The description does not add meaningful parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Deletes') and resource ('a list of Test Runs'), and explicitly distinguishes cardinality by naming the sibling `deleteTestRun` for single-item deletion. An agent can immediately tell what this tool does and how it differs from the single-delete alternative.

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

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

It clearly states when to use this tool (full collection or batch) and when to use an alternative (`deleteTestRun` for a single item by ID). It also advises setting `dry_run: true` first to preview, which is actionable usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's main added value is explaining what destruction means ('irreversible — data removed or overwritten by this call cannot be recovered through the API') and describing the dry_run preview behavior, including that the Authorization header is redacted. The trailing clause about 'structured content when the tool declares an output schema' is conditional on a schema this tool does not have, which slightly muddies the otherwise clear disclosure.

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 cardinality, then effect, then tip — a sensible ordering. It is slightly longer than needed because the dry_run/output-schema sentence restates schema-level detail and ends on a conditional that does not apply here.

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, single-item delete with full schema coverage and no output schema, the description covers the essentials: scope, irreversibility, the batch alternative, and a safe-preview path. Missing only minor prerequisites such as required permissions or behavior when the parameter ID does not exist.

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 every parameter (including dry_run's redaction/byte-length semantics) is already documented in the schema. The description adds only the notion that testParamId targets a single item, which is marginal over 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?

States a specific verb and resource ('Deletes the specified Test Parameter for the specified Test Run') and immediately disambiguates from the nearly identically named sibling deleteTestRunTestParameters by declaring its cardinality ('targets a single item by ID'). An agent can pick the right tool 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 routes the agent: use deleteTestRunTestParameters for the full collection or a batch, and use this one for a single item by ID. It also gives an actionable pre-call recommendation (set dry_run: true first to validate and preview), which is concrete operational guidance rather than vague context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's irreversibility warning is partly redundant, but it adds value by stating recovery is impossible via the API and by documenting dry_run preview semantics (redacted auth header, binary payload summarized) that annotations do not cover. It does not disclose permission requirements or side effects on entities referencing the definition.

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 irreversible effect and the dry_run tip are front-loaded in two tight sentences. The trailing sentence about structured content output is generic boilerplate that does not apply here (no output schema) and slightly dilutes the payload.

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 no-output-schema delete, the description covers the mutation, the irreversibility, and a safe verification path. What's missing is only the collateral behavior (what happens to test parameters/records still referencing the definition) and permission requirements.

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 documented in the schema already; that sets the baseline at 3. The description restates only the dry_run behavior (already in the schema) and adds no syntax, format, or scoping detail for projectId/testRunId/testParamId.

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?

Names a specific verb and resource (delete a Test Parameter Definition scoped to a Test Run), which is unambiguous. However it does not distinguish itself from the very similar siblings deleteTestRunTestParameter and deleteTestRunTestParameters, so an agent must infer the definition-vs-value distinction from naming alone.

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 tip (run with `dry_run: true` first to validate), which is real guidance. But it says nothing about when this tool applies versus the near-identical sibling delete tools, nor about prerequisites such as permissions or whether dependent test parameters block the delete.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, but the description adds important context beyond them: the effect is irreversible and cannot be recovered through the API, and dry-run previews are returned as normal text or structured content. It does not discuss permissions or rate limits, but the safety profile is substantially clarified.

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

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

The description is front-loaded with the core action and scope, followed by the sibling alternative and safety tip. It is slightly longer than necessary because the executor/output-schema preview explanation is meta-level detail, but every sentence remains relevant.

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 batch-delete tool with no output schema, the description covers the key needs: what is deleted, scope, singular alternative, irreversibility, and dry-run validation. It does not describe the actual deletion response or error behavior, but annotations and the dry-run guidance cover the main safety concerns.

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 detailed `dry_run`, `projectId`, `testRunId`, and `requestBody` descriptions already carry most parameter meaning. The description adds useful cardinality context ('full collection or a batch') and dry-run workflow guidance, but does not go much beyond the schema's own parameter documentation.

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

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

The description states a specific verb and resource: 'Deletes a list of Test Parameters for the specified Test Run.' It also clarifies scope as 'the full collection or a batch,' which distinguishes this plural/batch tool from the singular sibling `deleteTestRunTestParameter`.

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

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

It explicitly routes single-item deletion to `deleteTestRunTestParameter` instead, and recommends using `dry_run: true` first to validate and preview the request. That gives an agent clear selection and safety guidance rather than leaving it 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds useful behavioral consequence beyond annotations by stating the effect is irreversible and that removed data cannot be recovered through the API, plus explaining the dry_run preview behavior.

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

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

The description is front-loaded with purpose, cardinality, and sibling routing, then briefly covers irreversibility and dry-run preview. It is efficient and well-structured, though the final sentence about preview return format is slightly more detailed than strictly needed for tool selection.

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

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

Given the destructive nature, 100% schema coverage, and no output schema, the description provides enough context: it states what the tool deletes, how to avoid accidental deletion via dry_run, the irreversibility, and the batch alternative. An agent has what it needs to call this tool correctly and safely.

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 in the input schema. The description reinforces the single-item-by-ID targeting and highlights `dry_run`, but does not add much parameter-level detail beyond what the schema already provides, 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?

The description states a specific verb and resource: it deletes a specified Test Step. It also clarifies cardinality as a single item by ID and contrasts this with deleteTestSteps for full collection or batch operations, so an agent can distinguish it from siblings 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?

It explicitly names the alternative for batch or full-collection deletion (`deleteTestSteps`) and gives a concrete prerequisite strategy: set `dry_run: true` first to validate arguments and preview the request. This covers when to use this tool versus a sibling and how to safely invoke 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 declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the useful framing that the effect is irreversible and not recoverable through the API, plus the dry_run preview path and the note that the preview comes back as text (and structured content when an output schema exists). It does not cover failure modes such as a missing attachment ID or permission errors, so it earns a solid but not full 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?

Front-loaded with purpose, then cardinality, alternative, and effect — good ordering with no wasted preamble. The final sentence about the executor returning structured content when the tool declares an output schema is conditional boilerplate that does not apply here (no output schema) and mildly pads an otherwise tight description.

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, seven-required-parameter delete with no output schema, the definition covers what matters most: single-item scope, the batch alternative, irreversibility, and a safe dry-run path. Gaps remain around error behavior (nonexistent attachment, insufficient permissions) and whether deletion cascades, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100% and each of the eight parameters is documented in the schema, including projectId scoping and testCaseProjectId cross-project nuances. The description adds only the `dry_run` usage hint, which the schema already explains; otherwise it contributes nothing about parameter meaning. Baseline 3 applies when the schema carries the load.

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 ("Deletes the specified Test Step Result Attachment") and immediately disambiguates cardinality, targeting a single item by ID. It explicitly names the sibling `deleteTestStepResultAttachments` for the batch case, so an agent can separate the two without reading 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?

Explicit routing rule: use this for one item by ID, use the plural sibling for the full collection or a batch. It also gives a concrete recommended precondition ("set `dry_run: true` first to validate the arguments"), which is exactly the when-to-use guidance an agent needs before an irreversible call.

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, but the description adds real value by stating deletion is irreversible and unrecoverable through the API, plus the dry_run preview contract (text vs. structured content). Minor gap: no note on auth scope or partial-failure behavior for mixed batches.

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 the sibling disambiguation before the safety notes, which is the right order. The final sentence about executor preview output is marginally tangential but still useful context for dry_run consumers.

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 8-parameter tool with a nested requestBody and no output schema, the description covers cardinality, the alternative, irreversibility, and the dry_run escape hatch. It doesn't address how batch IDs are supplied or what happens if some IDs are invalid, but the schema fills most of that.

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

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

Schema description coverage is 100% and includes a detailed dry_run definition, so the schema already carries parameter meaning. The description only echoes the dry_run tip without adding syntax for requestBody, iteration, or testStepIndex beyond what the schema provides — baseline 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?

States a specific verb (deletes) and resource (list of Test Step Result Attachments), and explicitly contrasts its batch cardinality with the singular sibling `deleteTestStepResultAttachment`. An agent can distinguish it from the many other delete* tools without opening the schema.

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

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

Names the alternative tool explicitly and the condition that selects it (single item by ID vs. list/batch). It also recommends a dry_run-first workflow, so the agent knows both which tool to pick and how to sequence the call safely.

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. The description adds meaningful context beyond annotations by stating the effect is irreversible and data cannot be recovered through the API, and by explaining dry_run preview behavior. It does not describe authorization requirements or rate limits, so it falls short of 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?

The description is front-loaded with purpose, cardinality, and the sibling alternative, and every sentence contributes something useful. The final sentence about executor preview output is somewhat verbose and generic, slightly reducing conciseness.

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 batch-deletion tool with rich annotations, full schema coverage, and no output schema, the description supplies exactly the missing context an agent needs: irreversibility, sibling routing, and dry_run preview behavior. Nothing critical is omitted.

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 parameters are already documented structurally. The description mentions dry_run and batch cardinality but adds little parameter detail beyond what the schema provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: it deletes a list of Test Steps. It also clarifies cardinality as targeting the full collection or a batch, and explicitly differentiates itself from the single-item sibling deleteTestStep. An agent can distinguish it from siblings without inspecting schemas.

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

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

It names the alternative for single-item deletion explicitly: use deleteTestStep instead. It also gives a concrete safety-oriented usage tip: set dry_run true first to validate and preview the request. Both when-to-use and when-to-use-a-different-tool guidance are 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 declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known; the description still adds real value by saying the effect is irreversible and that data cannot be recovered through the API, plus what dry_run returns. The closing sentence about structured content is slightly muddled since no output schema is declared, which keeps it off 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 purpose, then the consequence, then the safe-path tip — a sensible order. The final sentence about text vs structured preview is meta-commentary that adds little for the calling agent and is the weakest part of the text.

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, no-output-schema mutation with fully documented parameters, the description covers the critical unknowns: irreversibility and a validation path. It does not address behavior when the attachment is absent or permission requirements, but those are secondary for this tool shape.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema carries projectId/workItemId/attachmentId semantics. The description adds workflow meaning for dry_run (preview exact request without sending), which goes beyond the boolean's type-level documentation.

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

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

States a precise verb and resource ("Deletes the specified Work Item Attachment") and scopes it to exactly one object type, which cleanly separates it from the many other attachment-delete siblings in the list (deletePageAttachment, deleteTestRunAttachment, deleteTestStepResultAttachment). 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?

Gives a concrete operational guideline — run dry_run first to validate and preview — which is genuine usage advice rather than a restatement. It stops short of naming when not to use it or which sibling to reach for instead (e.g. patchWorkItemAttachment), so it is clear context but not full 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 destructiveHint=true and idempotentHint=true, so the description's job is to add context — and it does: irreversibility is spelled out ("data removed or overwritten by this call cannot be recovered through the API") and the dry_run preview mechanism is described in detail, including that Authorization is redacted and binary payloads are summarized by byte length plus how the preview is returned. That is substantive behavioral disclosure beyond the flag set.

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?

Scope, alternative, safety consequence and the dry_run tip are front-loaded in four short sentences. The final clause about output schemas is slightly tangential and could be trimmed, but nothing is redundant.

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

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

For a destructive, single-scope delete with no output schema, the description covers everything an agent needs: which project parameter, what gets destroyed irreversibly, when to use the sibling, and how to safely preview first. No output schema exists, so return values need not be explained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by explaining the operational purpose of `dry_run` (validate and preview the exact request without sending) and tying `projectId` to the tool's one-project scope, which is more than the schema restates.

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?

"Deletes a list of Work Items. Scope: one project (requires a project ID)." gives a specific verb (delete), resource (Work Items), cardinality (a list) and scope (single project). It explicitly names `deleteAllWorkItems` as the cross-project sibling, so the agent can distinguish the two without reading 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?

Names the alternative tool and the exact condition that selects it ("To act across all projects, use `deleteAllWorkItems` instead"). It also prescribes a workflow (set `dry_run: true` first to validate), leaving nothing 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?

Goes well beyond destructiveHint: true by spelling out that the effect is irreversible and that removed data cannot be recovered through the API. It also discloses exactly what dry_run does and how the preview is returned, which an agent cannot infer 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?

Front-loads the distinction and irreversibility in the first two clauses, then groups alternatives and the dry_run tip in a clear order. Slightly padded by the closing sentence explaining text vs structured preview output, which is only marginally actionable.

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 the risk profile, alternatives, and safe-preview workflow for a destructive nested-body tool with no output schema. The one gap is that the description never explains why a DELETE-style relationship removal requires a requestBody object with a data array, which is the most likely source of a malformed 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 coverage is 100%, so the baseline is 3; the description reinforces 'one named relationship' and the dry_run-first tip, but adds no new detail about relationshipId naming, projectId scoping, or what the required requestBody must contain.

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 ('Removes one named JSON:API relationship from a Work Item') and immediately disambiguates the most dangerous confusion: 'this edits linkage and does not delete related Work Items.' That single clause separates it from deleteWorkItems and deleteLinkedWorkItem in a crowded sibling list.

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

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

Names inspection alternative getWorkItemsRelationships and points to 'linked-work-item tools' for roles and related-item detail, plus a recommended dry_run-first workflow. The reference to linked-work-item tools is collective rather than naming a specific sibling, and no explicit 'do not use when' exclusion is given for patchWorkItemRelationships.

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, but the description adds the critical consequence the annotation cannot express: the deletion is irreversible and data cannot be recovered through the API. It also documents the dry-run preview behavior and how that preview is surfaced to the caller.

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, cardinality, and the sibling alternative before the risk note and dry-run tip — good ordering with no filler. The closing sentence about the executor returning structured content only when an output schema is declared is meta-noise here, since this tool declares no output 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?

Covers the essentials for a destructive single-item delete: scope, alternative, irreversibility, and a safe validation path, with no output schema to explain. The one gap is the conditional sentence about structured preview output, which is inapplicable and slightly muddies the dry-run guidance.

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 all four parameters, including the fully documented `dry_run`, are already explained in the schema. The description adds only the generic note that targeting is by ID, which does not extend the individual parameter meanings. 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 ("Deletes the specified Work Record") and immediately scopes it with cardinality ("targets a single item by ID"). It explicitly names the sibling `deleteWorkRecords` as the batch alternative, so the agent can distinguish the two without opening either schema.

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

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

Gives an explicit routing rule (single item here, full collection or batch via `deleteWorkRecords`) plus a concrete operational recommendation to run `dry_run: true` first. Both when-to-use and when-to-use-something-else are 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 openWorldHint=true, so the description's main added value is the explicit irreversibility statement ('cannot be recovered through the API') and the dry_run preview semantics, including how the preview is surfaced. It adds no detail on permissions or partial-failure behavior.

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

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

Front-loaded with the operation, then sibling disambiguation, then effect, then tip — a sensible ordering where each sentence carries distinct information. The final sentence about normal text vs. structured preview output is slightly verbose for what it conveys.

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

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

For a destructive 4-parameter nested-body tool with no output schema, the description covers scope, safety effect and the dry_run validation path, which is most of what an agent needs. It does not describe the success response or error behavior for invalid IDs.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining batch vs. full-collection targeting for `requestBody` and by describing what `dry_run: true` produces (redacted auth header, byte-length summary of binaries) rather than just naming it.

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

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