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

Annotations already disclose that this is a non-read-only, non-idempotent, open-world mutation. The description adds the PATCH endpoint and the in-progress state condition, but it does not explain what cancellation does to the run, whether it is immediate, or what permissions are required.

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 with the core action. However, the first two sentences are redundant, repeating that it cancels an action run, which keeps it from being maximally concise.

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

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

For a mutation tool with a required nested body and no output schema, the description is too thin. It does not explain what the body should contain, what the response is, or what happens to a run after cancellation, leaving important call-time context 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?

Top-level schema description coverage is high, so the schema already documents the id and body parameters. The description adds no parameter-level detail, and it does not clarify the large nested body object, but the baseline for high schema coverage is 3.

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

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

The description states a specific verb and resource: cancel an action run. It also narrows scope to runs currently being executed. It does not explicitly differentiate from nearby siblings such as delete action run or get action run, so it falls short of a 5.

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

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

The phrase 'currently being executed' implies the tool applies only to in-progress runs, but the description gives no explicit when-to-use guidance, exclusions, or alternative tools. Usage is therefore implied rather than clearly instructed.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds nothing behavioral beyond re-stating the POST path already duplicated in the annotation title — it does not say that each call appends a new version, whether the supplied body replaces the action definition, or what permissions/project scoping are required for non-system actions.

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?

Line 1 and line 2 say the same thing in slightly different words, and line 3 is just the HTTP method and path already present in the annotation title. The text is short, but almost none of it earns its place; information density is near zero rather than front-loaded with useful content.

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?

This is a mutation endpoint with a large nested request body and no output schema, yet the description says nothing about the response (version id? full object?), whether the new version becomes active/released, or how the body relates to the existing action definition. For a 3-required-param nested-payload creation call, that leaves meaningful unknowns.

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

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

Schema description coverage is 100%, so the baseline of 3 applies: id, projectId and body are documented in the schema. The description contributes no extra meaning, which is a real gap given the nested body requires a full action payload (actionType, entrypoint, runtime, orgId, name) that an agent must infer from the schema alone.

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

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

The description names a specific verb and resource ("Create a version for an action") and repeats it in the second line, so the agent knows exactly what object is produced. It does not, however, distinguish this from nearby siblings such as abx_release_action_version, abx_delete_action_version, abx_restore_action_version, or abx_put_actions_by_id, which an agent must disambiguate by name 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?

There is no statement of when to use this rather than the release/unrelease/restore/patch version siblings, and no prerequisites (e.g. that the action must already exist, or that a version can be created without releasing it). The only guidance is the verb itself, which is exactly the bare minimum.

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, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond repeating that it deletes, such as what force does, whether deletion is reversible, or what project scoping is required.

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 short and front-loaded with the verb, but the first two lines repeat the same delete-action idea. The endpoint line also duplicates the annotation title rather than adding useful information.

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

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

Annotations cover the destructive and idempotent profile, but the description omits important operation-specific context for a delete tool with a force parameter and projectId requirement. An agent still lacks guidance on force semantics and non-system action scoping.

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

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

The schema already describes id and projectId, while force has no description; schema coverage is 67%. The description only repeats that a specific ID is used and does not explain the force flag or the projectId requirement for non-system actions.

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

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

The description gives a specific verb and resource: "Delete an action" and "Deletes an action with a specific ID." The phrase "specific ID" implies single-action deletion, which distinguishes it from bulk alternatives like abx_delete_multiple_actions, but no sibling is explicitly named.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention abx_delete_multiple_actions or any other sibling, nor does it state prerequisites or when deletion should be avoided.

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 safety profile is covered structurally. The description adds only a restatement of the name plus the raw DELETE endpoint, which is already reflected in the title; it discloses nothing new such as irreversibility, per-ID error handling, or whether partial failures roll back.

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

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

Very short and front-loaded, but the first two sentences say the same thing twice ('Delete multiple action runs' / 'Deletes multiple action runs with their specific ID'), and the trailing REST path duplicates the annotation title. Half the text 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, open-world bulk-delete with no output schema, the description should at minimum signal irreversibility and distinguish itself from the single-ID sibling. Neither is present, leaving gaps that annotations alone do not fill for an agent choosing between delete variants.

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% — the single 'body' property is documented as 'IDs of the action runs'. The description's 'with their specific ID' is slightly misleading in the singular, given the body is an array of strings, but adds no real meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete multiple action runs') and clarifies that IDs are supplied, which distinguishes it from a bulk-everything delete. However, it never acknowledges the closest sibling abx_delete_action_runs_by_id, so an agent cannot tell from the text whether this is the plural form of that tool or something different.

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

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

There is no statement of when to use this versus abx_delete_action_runs_by_id, abx_cancel_action_run, or abx_delete_action. No prerequisites, no warnings that the deleted runs are permanently removed, and no indication of what happens to runs that are still 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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no statement of irreversibility, whether related runs/logs are removed, or what happens when the ID doesn't exist or the run is in progress.

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?

Very short, but the first two lines say the same thing twice ('Delete an action run' / 'Deletes an action run with a specific ID'), so nearly half the text is redundant. The HTTP route is useful for API-literate agents but is also duplicated in the annotation title.

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

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

For a one-parameter destructive call whose annotations and schema are already complete, the description is minimally sufficient. It still leaves the agent without any consequence or precondition information for an irreversible operation.

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

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

Only one parameter, and the schema already documents it at 100% coverage ('ID of the action run (path)'). The description restates the same idea without adding format, source, or lookup guidance, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Deletes an action run with a specific ID', which implicitly contrasts with the bulk sibling abx_delete_action_runs. It doesn't name that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

No guidance on when to use this versus abx_delete_action_runs, abx_cancel_action_run, or the get/list siblings. No prerequisites, permissions, or state conditions (e.g., whether the run must be finished) are given.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond restating the operation and echoing the HTTP route; it doesn't say whether the secret is permanently removed, whether callers need specific permissions, or how errors surface.

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

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

The core action is front-loaded, and the HTTP route is mildly useful for endpoint mapping. However, 'Delete an action secret' and 'Deletes an action secret' are pure duplication, so roughly a third of the text earns no place.

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

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

For a single-parameter destructive delete with complete annotations and full schema coverage, the description is adequate but thin. It never states reversibility or failure behavior, which matters for a destructive operation.

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

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

There is a single parameter and the schema documents it fully ('ID of the action secret (path)'), so the schema does the work. The description adds no extra semantics, which meets the baseline-3 expectation at 100% schema coverage.

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

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

The description names a specific verb and resource ('Delete an action secret'), so the agent instantly knows the operation. It does not distinguish this from siblings such as abx_get_action_secrets, abx_put_action_secrets_by_id, or abx_post_action_secrets, but the intent itself is unambiguous.

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

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

There is no guidance on when to use this versus the get/put/post siblings, no note about prerequisites such as needing the secret's ID first, and no mention of what happens if the secret doesn't exist. The agent must infer everything from the tool name.

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 carried elsewhere. The description adds nothing beyond that — no statement about permanence, whether released versions can be removed, or any authorization requirement, only the REST path.

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

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

Three lines where one would do: line 1 and line 2 are the same sentence with different capitalization, which is pure redundancy rather than front-loading. The only unique content is the raw endpoint.

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

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

For a three-required-parameter destructive tool with no output schema but full annotation coverage, the definition is minimally sufficient — an agent can identify and invoke it. It still omits the consequences of the delete and the projectId scoping rule.

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 id, versionId, and projectId all documented in-schema, so the baseline of 3 applies. The path template in the description loosely corroborates that id and versionId are path segments but adds no meaning beyond the schema, and projectId's unusual role for non-system actions is left to the schema alone.

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 verb+resource ("Delete an action version") is unambiguous, but the second line merely restates the first verbatim and the third is the raw HTTP route. It never distinguishes this from nearby siblings such as abx_delete_action, abx_restore_action_version, or abx_release_action_version.

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

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

No when-to-use guidance, no exclusions, no mention of alternatives. An agent gets no help deciding between deleting a version versus deleting the whole action (abx_delete_action) or restoring it (abx_restore_action_version).

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 safety profile is covered without the description. The description adds nothing beyond that: no permissions needed, no statement on whether deletes are atomic, and no mention of what happens when an id does not exist.

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, which is good, but the first two lines restate the same fact ('Delete multiple actions by their id and projectId' / 'Deletes actions with a specific ID and projectId') without adding information. Three lines for one sentence of content.

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-mutation tool with no output schema, the description says nothing about response, partial-success behavior, permission requirements, or limits on batch size. The safety annotations cover only part of what an agent needs before 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 coverage is 100%, so the baseline would be 3, but the description actively misleads: it says actions are deleted 'by their id and projectId' while the schema requires id and orgId and treats projectId as optional. An agent could omit a required field or assume an optional one is mandatory.

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

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

States a specific verb and resource (delete multiple actions) and the endpoint path, so the operation is identifiable. However it does not distinguish itself from the sibling abx_delete_action (single delete), leaving the 'multiple' scope to be inferred only by the 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?

There is no guidance on when to use bulk delete versus the sibling abx_delete_action, no prerequisites, and no note about partial failures. The agent must infer selection purely from tool names.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description contributes one genuinely useful behavioral fact beyond them — the result is a zip bundle, which matters since no output schema exists — but says nothing about permissions, whether the export is synchronous, or size limits.

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 operative sentence is short and front-loaded, but the first line merely restates the name and the third line is a raw POST path that duplicates the annotation title, so roughly a third of the text 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?

With one required body parameter at full schema coverage, annotations present, and no output schema, the description covers the core contract and the return format. It still leaves gaps an agent would want — whether the response is a direct download versus a job handle, and what happens when an action identity is 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 coverage is 100% and the nested body/actions identity object is fully documented in the schema, so baseline 3 applies. The phrase "the specified actions" mirrors the actions array but adds no semantics about id/orgId/projectId or how multiple identities are handled.

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 ("Exports the specified actions") and adds the output form ("as a zip bundle"), which lets an agent distinguish it from siblings like abx_import_actions or abx_get_all_actions. It does not explicitly name an alternative, but the operation is unambiguous.

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

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

Usage is only implied by the verb: an agent can infer this is the tool for pulling an action bundle out of the system. There is no statement of prerequisites, when to prefer this over listing actions, or any exclusion, and the raw endpoint line adds nothing to selection.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, open-world GET. The description adds the cross-project scope and the endpoint, but does not explain pagination behavior, authentication needs, or whether multiple actions can share the same ID.

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

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

The description is short, but it repeats the same idea in two nearly identical sentences and then lists the endpoint. It is not bloated, but the redundancy prevents it from being tightly front-loaded.

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

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

For a read-only GET with full schema coverage and strong annotations, this is minimally adequate. However, because there is no output schema, the description should clarify whether same-ID actions across projects are returned as a collection and how paging behaves.

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 all six parameters. The description only echoes the ID and all-project scope and adds no syntax or behavioral meaning 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 names a specific operation and resource, but the phrase 'Fetch all actions by ID' is internally ambiguous: a by-ID lookup usually returns one action, while 'all actions' implies many. It also does not distinguish this tool from sibling listing or per-action tools such as abx_get_all_actions.

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

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

The description gives no explicit guidance on when to use this tool, when not to use it, or which sibling to use instead. The 'across all projects' wording implies a scope, but the agent is left to infer the selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds nothing beyond the endpoint path: no word on behavior for an unknown/expired ID, whether run logs or output are included, or whether deleted runs are visible.

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

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

Three lines that repeat the same fact three times: fetch, retrieve, and the GET path. Front-loaded and short, but genuinely redundant rather than dense.

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

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

For a one-parameter read with full annotation coverage, the basics are there. Without an output schema, though, the description should at least hint at what an action run entity contains, since that determines whether the agent calls this or a projections/logs sibling.

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

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

Schema coverage is 100% and the single parameter is documented as the path ID, so the schema carries the semantics. The description only restates 'by its ID' and adds no format hints (UUID vs. opaque string) beyond that baseline.

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

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

States a specific verb and resource: fetch/retrieve an action run entity by ID, plus the underlying endpoint. It does not distinguish itself from nearby siblings such as abx_get_action_runs_by_action_id (list runs for an action) or abx_get_all_action_run_projections, so an agent must infer which retrieval variant it needs.

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

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

There is no guidance on when to use this versus the sibling list/query tools for action runs, nor any prerequisite (e.g. needing a run ID obtained from abx_get_action_runs_by_action_id). The only implied usage is 'you have an ID'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds nothing beyond that — no pagination behavior, ordering, or response characteristics — and merely restates 'fetch all' twice.

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

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

Three lines say the same thing: 'Fetch all action runs of an action', 'Retrieves all action runs of an action', and the GET path. The duplication is waste, not reinforcement, and nothing is front-loaded beyond the first line.

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

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

For a simple read-only list endpoint with full schema coverage and rich annotations, the description is adequate but thin — it omits any hint of return shape or list ordering, which would help since there is no output schema.

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

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

Schema description coverage is 100%, with id, page and size each documented inline, so the baseline is 3. The description only echoes the path parameter '{id}' and adds no semantics for pagination parameters beyond the schema.

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

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

States a specific verb and resource ('Fetch all action runs of an action') and the REST path confirms the scope is limited to a single action id. It is distinguishable from abx_get_action_run_by_id (singular) by wording, though it does not explicitly name siblings like abx_get_all_action_run_projections.

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

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

No guidance on when to use this versus alternatives such as abx_get_all_action_run_projections or abx_get_action_run_by_id, and no mention of prerequisites. Usage is only weakly implied by the 'of an action' phrasing.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive GET. The description adds the organization-level scope and HTTP endpoint, but it does not explain return format, pagination, or whether secret values are returned or redacted.

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 but redundant: 'Fetch all action secrets' and 'Retrieves all action secrets for given organization' restate the same purpose before repeating the endpoint. It is front-loaded but not maximally efficient.

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

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

For a simple, parameterless list operation with rich safety annotations and no output schema, the description is adequate to invoke correctly. It leaves some context gaps around sensitive-data handling and response shape, but those are secondary for selection and 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?

There are zero parameters, so there is no parameter semantics to document. The baseline for a parameterless tool is 4.

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: fetch all action secrets for the organization. It is clear it is a bulk retrieval, but it does not name or distinguish against siblings such as abx_get_action_secrets_by_id or abx_post_action_secrets.

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 says it retrieves all action secrets, but gives no explicit when-to-use guidance, no exclusions, and no mention of alternatives like the by-id secret lookup or the create/delete secret tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so safety is covered. The description only repeats 'Fetch'/'Retrieves' and supplies the endpoint path; it adds no behavioral context such as authentication requirements, pagination, or how secret values are exposed.

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 with the action. The first two phrases are somewhat redundant ('Fetch action secret' / 'Retrieves action secret by given id'), but the endpoint path is useful and there is no filler.

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

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

For a simple read-by-ID tool with full schema coverage and strong annotations, the core operation is adequately described. However, with no output schema, the description does not clarify what is returned (e.g., secret value or metadata) or distinguish this from the list endpoint, leaving some ambiguity.

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

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

Schema coverage is 100% and the sole parameter is documented as 'ID of the action secret (path)'. The description adds nothing beyond the schema, so the baseline of 3 for high-coverage schemas applies.

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

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

The description clearly states a specific verb and resource ('Fetch action secret') and confirms retrieval by ID. It does not explicitly distinguish this tool from siblings such as abx_get_action_secrets (list) or abx_get_action_secret, but the by-ID intent is still evident.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must infer from the name alone that this is the single-item retrieval counterpart to the list endpoint.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds only the REST path (GET /abx/api/resources/action-templates/{id}), which is mild extra context but discloses nothing new about behavior, errors, or returns.

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

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

The three lines are front-loaded and short, but the first two sentences restate the same fact and the third merely repeats the endpoint already present in the annotation title. Roughly half the text is redundant with structured fields.

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

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

For a one-parameter idempotent read with full annotation coverage and complete schema descriptions, the definition is complete enough to invoke correctly. Missing detail is limited to what happens on an unknown ID, which is minor for a simple GET.

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

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

Schema coverage is 100% and the single parameter already documents that it is the path ID of the action template. The description says 'by its ID' but adds no format, source, or lookup guidance beyond the schema, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Fetch an action template') and scopes it to a single entity via 'by its ID', which implicitly distinguishes it from the sibling abx_get_all_action_templates. It never names the list sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by 'by its ID' — an agent can infer this is the single-record lookup rather than the list tool — but there is no explicit when-to-use/when-not guidance, no prerequisites, and no named 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 readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description usefully adds that projections are a lightweight UI representation, but says nothing about pagination defaults, ordering, or result size limits — and notably the required 'projection' flag makes the naming slightly confusing given the endpoint's own purpose.

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

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

Three short, front-loaded lines with no padding. There is mild redundancy between 'Fetch all action run projections' and 'Retrieves projections of all action runs', which keeps 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?

For a read-only list endpoint with full schema coverage and complete annotations, the description supplies everything needed to select and invoke it, including the lightweight/UI intent and the underlying route.

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 page, size and projection are already documented in the schema. The description adds no additional semantics about paging behavior, acceptable values, or why projection is required despite the tool already returning projections.

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 (fetch/retrieve action run projections) and clarifies the payload is a lightweight representation for UI use. This distinguishes it in substance from siblings like abx_get_action_run_by_id or abx_get_action_runs_by_action_id, though it never names them explicitly.

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

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

The 'lightweight representation for UI' note implies when this tool is preferable to full-entity retrieval, but there is no explicit when-to-use statement or reference to the filtered/bulk siblings. Guidance is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds that it retrieves a count matching name criteria, but it does not clarify how pagination, projection, or the count return value behave, and 'by ID' introduces confusion.

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, but the first two sentences repeat the same 'count of subscribable actions' idea and the 'by ID' wording is not clarified. It could be compressed into one precise sentence.

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

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

Given four parameters, no output schema, and many sibling action-related tools, the description should clarify whether this returns a count or entities and how it differs from related ABX tools. It leaves those selection-critical questions unresolved.

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 page, size, projection, and nameCriteria are already documented in the schema. The description only echoes the name criteria concept and adds no extra parameter semantics, which is acceptable given full schema coverage.

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

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

The description says it fetches a count of 'subscribable actions by ID', but the tool name suggests listing all actions and the schema has no ID parameter. The phrase 'matching the name criteria' helps, but the count-vs-list ambiguity and undefined 'subscribable' leave the purpose muddled.

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

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

There is no guidance on when to use this tool versus siblings such as abx_get_action_by_id, abx_get_all_action_templates, or abx_get_all_action_run_projections. It also does not state exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the description adds nothing about safety. It also says nothing about collection size, pagination, filtering, or ordering — the behaviors that actually matter for a 'fetch all' endpoint. The three lines merely restate the same fact plus the raw HTTP path.

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

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

Three lines that repeat the identical idea ('Fetch all action templates' / 'Retrieves all action templates') plus the HTTP path. Only one sentence of content is present; the rest is duplication with no front-loaded added value.

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

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

Annotations cover the read-only safety profile and there is no output schema or parameters to explain, so the basics are covered. However, for a 'get all' collection endpoint, an agent would benefit from knowing whether the response is paginated or how large it can be, and none of that is disclosed.

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

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

The tool takes zero parameters and the schema is fully specified, so there is nothing for the description to clarify. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb and resource: fetch/retrieve all action templates, and the endpoint path confirms it is a collection read. It is implicitly distinguishable from the sibling abx_get_action_template_by_id, but the description never names that sibling to make the contrast explicit.

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

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

No when-to-use or when-not-to-use guidance. The only signal is the word 'all', which weakly implies 'use this for the full collection rather than a single template', and no mention is made of the obvious alternative abx_get_action_template_by_id.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered structurally. The description adds only the raw endpoint path and otherwise repeats the operation; it says nothing about pagination, result ordering, or the project-scoping behavior for non-system actions.

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 first two lines are near-verbatim restatements of each other and the third is a bare HTTP path, so roughly half the text is redundant. It is short and front-loaded, but the duplication means not every line earns its place.

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

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

For a simple read-only lookup with full schema coverage, rich annotations and no output schema, the definition is functionally adequate. It nonetheless omits the practical gotcha that non-system actions need a projectId, and gives no hint of the shape or size of the returned flow list.

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

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

Schema description coverage is 100%, so both parameters are already documented, which sets the baseline at 3. The description corroborates that the ID identifies the action being searched for but adds nothing about the conditionally required projectId.

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

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

States a specific verb and resource: fetch/retrieve the list of action flows that use a given action, scoped by action ID. That is enough for an agent to distinguish it from the many abx_* CRUD siblings, though the description never explicitly contrasts itself with them.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. abx_get_action_by_id for the action itself), and no note that non-system actions require projectId to be supplied. The agent must infer the usage context entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the unusual claim that this is a "Proxy" call and that results are scoped to an organization, without explaining pagination, response shape, or how organization scope is determined when no parameter exists.

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

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

Three short lines, yet the first two say the same thing ("fetch" / "Retrieves") and the third just restates the HTTP route already present in the annotation title. Front-loaded but partly 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?

A parameterless read with no output schema and annotations covering safety needs little, but the description omits pagination/result volume and never clarifies the organization scoping it mentions. Adequate, not complete.

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

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

There are zero parameters, which would normally be a baseline 4, but the phrase "for given organization" implies an organization input that does not exist in the schema. That mismatch can make an agent search for a parameter that isn't there, so it is scored below baseline.

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

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

States a specific verb and resource ("Retrieves provisioning endpoints") and pins the scope to an organization, plus the underlying GET path. It is clear what the tool returns, but it never distinguishes itself from the sibling abx_get_provisioning_endpoints_by_id beyond the word "all" in the 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?

No indication of when to call this versus abx_get_provisioning_endpoints_by_id, or what preconditions apply. The agent must infer that this is the unfiltered list variant from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds nothing beyond that – no pagination behavior, no default page/size semantics, no note on whether versions are returned newest-first, and no auth context for the projectId requirement.

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 content is short and front-loaded, but the three lines are near-verbatim restatements of the same fact, with the raw path adding little for an agent. Two of the three lines could be dropped without information loss.

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

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

For a simple paginated read with full annotation coverage, a fully documented schema, and no output schema to explain, the description supplies enough to call the tool correctly. Missing pagination/default-size hints are minor gaps rather than blockers.

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 all four parameters (id, projectId, page, size) are documented in the schema, so the baseline of 3 applies. The description contributes no additional meaning about parameter usage or interactions.

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

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

The description gives a specific verb and resource ('Fetch all versions of an action') and even names the underlying endpoint, so an agent can distinguish it from sibling version tools such as abx_create_action_version, abx_delete_action_version, and abx_release_action_version. It does not explicitly name or contrast any alternative, but the name-plus-scope is unambiguous.

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

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

There is no guidance on when to use this versus related tools, no preconditions, and no mention of the non-system vs system action distinction implied by the projectId parameter. The only signal is the implied 'list version history', which the agent must infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only that this is a 'proxy' call and the underlying REST route; it says nothing about behavior on a missing/invalid id or error conditions.

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

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

Three short lines, front-loaded with the purpose, so it is compact. But the second line is a misleading plural/organization claim that should either be removed or reconciled, so not every sentence earns its place.

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

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

For a one-parameter, read-only GET with no output schema and rich annotations, the definition is minimally sufficient. The internal inconsistency about scope (single endpoint vs. list for an organization) is the main gap an agent would notice when 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 coverage is 100% for the single 'id' parameter, so the baseline is 3. The phrase 'by self link' hints that the id is a self-link-style identifier rather than a plain UUID, which is marginal added meaning, but the description never clarifies whether it is the endpoint id, an org id, etc.

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 clause 'fetch a provisioning endpoint by self link' names a specific verb and resource and implies a by-id lookup that differs from the plural sibling abx_get_all_provisioning_endpoints. However, the next line ('Retrieves provisioning endpoints for given organization') is plural and organization-scoped, contradicting the by-id framing and leaving the agent unsure whether this returns one endpoint or many.

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

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

Usage is only implied: 'by self link' and the single 'id' path parameter suggest you call this when you already have an identifier. There is no explicit statement to use abx_get_all_provisioning_endpoints when you lack an id, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: it never explains how the import handles name collisions, whether existing actions are replaced, or whether authentication/scope constraints apply.

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 text is short, but the first two lines restate the same fact ('Import an action bundle' / 'Imports an action bundle and saves all actions'), and the raw HTTP route adds little for an agent choosing a tool. Front-loading is fine; redundancy costs it a point.

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?

This is a mutating import with a nested body object, a four-way conflict-resolution enum, and no output schema. The description should explain what the option values mean for existing actions and what the result is, but it stops at a paraphrase of the name.

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

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

With schema description coverage reported at 100%, the schema carries the parameter burden, so baseline 3 applies. The description does not compensate for the weakest point, namely the meaning of the option enum (FAIL/IGNORE/OVERWRITE/CREATE), which is the single most consequential decision in the call.

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

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

The description uses a specific verb and resource ('Import an action bundle') and clarifies the effect ('saves all actions'). It does not distinguish itself from nearby siblings such as abx_export or abx_post_actions, but the core purpose is unambiguous.

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

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

There is no statement of when to use this versus abx_export, abx_post_actions, or abx_create_action_version, nor any prerequisite context. The agent must infer usage entirely from the tool name and the raw POST path.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds one genuinely useful behavior beyond them: untouched properties are preserved. It omits permissions needed, whether the action's version state is affected, and why a PATCH body still has required fields.

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

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

Three short lines, front-loaded with the verb and the key patch semantics. The final line repeats the endpoint path that is already present in the annotation title, which is minor waste.

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

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

For a nested 26-property body with no per-property descriptions and no output schema, the description is thin: it says nothing about what the enum actionType values imply, which fields are meaningful together, or what the response contains. Adequate to identify the tool, not adequate to call it confidently with a complex payload.

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

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

Schema coverage is 100% (both `id` and `body` are documented), so the baseline is 3. 'Based only on the supplied properties' adds a little meaning about how body fields are interpreted, but the 26 nested body properties and the required actionType/entrypoint/name/orgId/runtime set 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?

Names a specific verb (patch) and resource (an action) and clarifies partial-update semantics with 'Updates the state of the action based only on the supplied properties.' It does not name the closely related sibling abx_put_actions_by_id, so an agent must infer the PATCH-vs-PUT split from the HTTP verb 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?

The phrase 'based only on the supplied properties' implicitly signals partial updates and therefore contrasts with a full-replace PUT, but the description never states when to prefer this over abx_put_actions_by_id, abx_create_action_version, or abx_restore_action_version, and gives no preconditions such as whether the action must be unreleased.

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

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

Annotations already declare the write/non-idempotent/open-world profile, so the description's main added value is the deprecation status and removal warning, which is genuinely behavioral context not captured by annotations. It does not describe side effects or what gets created, but the safety profile is covered.

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 deprecation tag and the action, with the replacement path last where it belongs. Slightly redundant in restating 'Create an action run' then 'Creates a new action run', but no substantive waste.

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

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

For a create tool with no output schema and a large nested body, the description covers purpose and deprecation but says nothing about required fields, expected result, or what state the new run starts in. Adequate but leaves real gaps an agent calling a creation endpoint would want.

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

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

Schema description coverage is 100% and the single 'body' parameter carries a full nested property list, so the description adds nothing about fields like runState, actionType, or actionVersionId. Baseline 3 is appropriate when the schema does all the work.

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 ('Creates a new action run') and the endpoint path, so an agent knows exactly what it does. It does not name the sibling tool that supersedes it (abx_post_actions_by_id_action_runs), which would have made the differentiation explicit.

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

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

Gives clear exclusions — 'deprecated and will be removed' — and points to the recommended replacement path POST /abx/api/resources/actions/{action-id}/action-runs. The guidance is in raw URL form rather than the MCP tool name, so the agent must map the path to a sibling itself.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the description's only added content is the raw POST path, which merely restates the annotation title. Nothing is said about side effects, authentication, or what happens on duplicate names.

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 three lines say the same thing three times ('Create an action', 'Creates a new action', 'POST /abx/api/resources/actions'), so length is wasted on redundancy rather than on useful detail. It is short but not efficient.

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

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

For a creation endpoint taking a ~25-property nested body with required fields like actionType, entrypoint, runtime and orgId, and with no output schema, the description should at least say what an ABX action is and what the required payload means. Instead it repeats the tool name and 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 description coverage is 100%, so the baseline is 3 even though the description says nothing about the single nested body parameter. Notably the schema labels the body 'Properties of the action to patch', a confusing mismatch for a create operation that the description does nothing to clarify.

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 ('Creates a new action'), which is enough to tell it apart from read/delete siblings like abx_get_all_actions or abx_delete_action. It does not, however, differentiate it from closely related write-path siblings such as abx_post_actions_by_id_action_runs or abx_put_actions_by_id.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites such as an existing org, runtime, or project, and no note about how it relates to version-creation or import tools. The agent is left to infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the fact that this mutates remote state is covered structurally. The description confirms execution occurs ('Runs the specified action taking into consideration the supplied configuration') and is consistent with those hints, but adds nothing beyond them - no mention of asynchronous behaviour, returned run identifier, or that runs can later be cancelled.

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 short and front-loads the verb 'Trigger'. It wastes a little space by restating the same idea twice ('Trigger an action run' / 'Runs the specified action...') and by appending the HTTP path, which the annotations title already carries.

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 trigger tool with a large nested body object and no output schema, the description should say what comes back (a run id? a run object?) and whether the call blocks or is asynchronous - both are completely absent. With no output schema to compensate, an agent cannot tell how to obtain or track the run it just started.

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 reported at 100%, and both top-level parameters carry descriptions ('ID of the action (path)', 'Configuration of the action run'), so the baseline of 3 applies. The phrase 'taking into consideration the supplied configuration' adds no actionable meaning - it does not say which of the ~20 nested body properties (inputs, runtime, timeoutSeconds, actionId) are actually honoured versus echoed.

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

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

The description gives a specific verb and resource: 'Trigger an action run' against /actions/{id}/action-runs, which is concrete enough for an agent to know this launches an action execution. However it never distinguishes this tool from the close sibling abx_post_action_runs, which appears to do the same thing via a different path, so the agent has no basis for choosing between them.

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

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

There is no when-to-use guidance at all: nothing explains when to pick this over abx_post_action_runs, or that abx_cancel_action_run and abx_get_action_run_by_id are the follow-on tools for an in-flight run. The only hint of usage is implied by the verb 'Trigger'.

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 readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false. The description adds no behavioral context beyond restating that this is a POST create operation, and says nothing about secret sensitivity, value handling, permissions, or response 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?

It is short and front-loaded, but the first two lines are redundant: 'Create an action secret' and 'Creates a new action secret' say the same thing. The endpoint line is useful, but the duplication means not every sentence earns its place.

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

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

Given a secret-creation mutation with no output schema, the description is too sparse. It does not explain what is returned, how secret values are handled, whether orgId is required, or why this differs from updating an existing secret.

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 body parameter and its nested fields are structurally documented. The description adds no meaning about the body fields such as name, orgId, value, or encrypted, so the schema does the work and the baseline score of 3 applies.

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

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

The description clearly states the verb and resource: create an action secret. The endpoint path confirms this is a collection POST, which distinguishes it somewhat from get/put/delete secret siblings, though it never names those 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?

It provides no explicit guidance on when to use this tool versus abx_put_action_secrets_by_id, abx_get_action_secrets, or abx_delete_action_secret. There is no mention of prerequisites, org scoping, or when creating a secret is appropriate.

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, idempotent=true, destructive=false and openWorld=true, so the safety profile is covered. The phrase 'new supplied state' hints at full-replace PUT semantics rather than partial update, which is genuinely useful, but the description does not say whether omitted fields are cleared or what a successful response contains.

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

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

Three short lines, front-loaded with the verb and state-change summary, with no filler. The path echo essentially repeats the tool title and adds little, keeping it short of 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?

For a mutation whose body is a large nested object and with no output schema, the description should say what replacement semantics mean for omitted fields and what comes back. Annotations cover the safety flags, but replace-vs-merge behavior and return shape remain unstated.

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

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

Schema coverage is 100% (id is documented as the path ID, body as 'Properties of the action to patch'), so the schema does the heavy lifting. The description adds nothing about the body's required fields (actionType, entrypoint, name, orgId, runtime) or how they must relate to the existing action, 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 ('Update an action') and the second line clarifies it replaces the action with the supplied state. However, it never distinguishes this PUT from the sibling abx_patch_actions_by_id or abx_create_action_version, so the agent must infer which mutation to pick.

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

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

There is no when-to-use guidance, no mention of the PATCH alternative in the sibling set, and no preconditions (e.g. that a version must exist or that the full required state is supplied). The agent gets context only from the raw HTTP path.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond them: it doesn't say whether a PUT fully replaces the secret (omitted fields cleared), what happens to the encrypted flag, or what the response contains. The nested schema description 'Action secret to create' for a PUT endpoint adds mild confusion.

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?

Extremely short, front-loaded, but the first two lines are near-duplicates ('Update an action secret' / 'Updates an existing action secret') and the third is a raw route. Little waste in length, but the repetition adds nothing.

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

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

For a mutation tool with a nested body object, no output schema, and no annotations explaining replace semantics, the description is too thin. An agent cannot tell whether omitted body fields are cleared or preserved, which matters materially for a PUT.

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 documents both the path id and the body object with its fields. The description contributes no additional meaning about which body fields matter or are required during an update, 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 ("Update an action secret") plus the underlying PUT route. It is distinguishable from siblings like abx_get_action_secrets_by_id and abx_delete_action_secret by the verb, but it never explicitly contrasts itself with abx_post_action_secrets or abx_put_actions_by_id.

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

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

No guidance on when to use this instead of abx_post_action_secrets (create) or abx_patch_actions_by_id, and no prerequisites such as required ID or permissions. The agent must infer update-vs-create semantics from the tool name alone.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and the title carries the PUT endpoint, so the description adds nothing new. It does not say what 'released' means operationally (e.g. version becomes deployable/visible), whether a version must first be unreleased, what permissions are required, or how projectId affects scope.

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?

It is short, but the first two lines restate the identical fact ('Mark an action version as released' / 'Marks an existing version of an action as released'), and the raw PUT path duplicates the annotation title. Redundancy rather than density.

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?

This is a state-mutating tool with no output schema and no description of the resulting state change, side effects, or prerequisites. For a release/state-transition operation, an agent needs to know the semantic effect of the action, which is absent.

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 id, projectId, and the nested body.version are fully documented in structured fields. The phrase 'existing version of an action' loosely reinforces the id/version pairing but adds no format, precondition, or constraint detail beyond the schema.

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

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

The first line states a specific verb and resource: mark an action version as released, with the underlying PUT endpoint. It's distinct from the inverse sibling abx_unrelease_action_version by implication, but the description never names that sibling or abx_restore_action_version, so the differentiation is left to the agent's inference.

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

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

There is no explicit when-to-use guidance and no mention of the closely related abx_unrelease_action_version or abx_restore_action_version tools. The agent must infer from naming convention alone which state-transition tool to pick.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=true, destructive=false), and the description adds that the current action state is replaced by the version's state, which is useful context about the effect. It says nothing about what happens to unsaved/current edits, required permissions, or the response, so it adds only moderate value. Note the soft tension: overwriting current state is arguably destructive while destructiveHint=false, but the description does not assert destructiveness, so this is not a contradiction.

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

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

The first two sentences restate the same idea ('restore the action state based on a specified version' vs 'change the current action state to the state specified in the version'), and the trailing PUT path duplicates the annotation title. Content is front-loaded but partially 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 3-required-param mutation with full schema coverage and no output schema, the description covers the core effect but omits practical detail such as the projectId requirement rationale (only in schema) and what the call returns. Adequate but with visible 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 three parameters (id, versionId, projectId) are already documented in the schema. The description only echoes the path semantics and adds no extra meaning, which is exactly the baseline-when-schema-covers case.

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 (restore) and resource (action state to a specified version), which is clearly distinct from siblings like abx_create_action_version or abx_release_action_version. It does not explicitly name or contrast those siblings, so it stops short of a 5.

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

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

The description implies the use case (roll an action back to a prior version's state) but never states when to choose this over adjacent tools such as abx_release_action_version or abx_get_all_versions, nor any preconditions. Usage must be inferred from the verb.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description's only additional content is the raw DELETE endpoint, which merely repeats the title. It says nothing about the consequence of unreleasing — whether existing deployments or subscriptions referencing the version break, whether runs fail, or that re-releasing via abx_release_action_version is the way back.

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

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

Three lines, two of which are redundant paraphrases of the first, and the third is a raw endpoint string duplicating the annotation title. The text is short but wasted space, and no consequence or guidance is front-loaded.

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

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

For a destructive, open-world mutation with no output schema, the description should describe the resulting state change and any downstream effects. It currently supplies only a restated purpose and the HTTP route, leaving an agent unable to predict the outcome of the call.

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

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

Schema description coverage is 100%, with both id and projectId documented in the schema itself, so the baseline of 3 applies. The description adds no meaning beyond the schema — notably it does not explain the path {id} versus the projectId scoping rule beyond what the schema already states.

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?

A verb+resource is present ("mark an action version as not released"), so the general intent is graspable. But the three lines restate the same thing and never clarify the unit of operation: the schema only accepts an action id, not a version id, leaving it ambiguous whether this unreleases one version, the current version, or all of them. It also doesn't distinguish itself from close siblings such as abx_release_action_version, abx_restore_action_version, and abx_delete_action_version.

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

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

There is no statement of when to use this versus the sibling release/restore/delete version tools, and no prerequisites or warnings. An agent must guess whether "unrelease" is a soft rollback, a deprecation, or a prerequisite for 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the endpoint path — no mention that answering is irreversible once submitted, that it likely requires the work item to be in a pending state, or who is authorized to answer.

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?

It is short and front-loaded, so nothing is wasted structurally. But the single content sentence is a tautological restatement of the name and the endpoint string does no semantic work for an agent that already sees the tool name.

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

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

This is a non-idempotent mutation with a nested, opaque `formEntries` object and no output schema. The description gives no hint about where form entries come from (e.g. the work item's form definition), what a successful answer does to the approval lifecycle, or what identifiers are needed.

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

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

Schema description coverage is 100%, so the schema carries the documentation burden and the baseline is 3. The description contributes nothing about the required uuid `id` (is it the work item id from approvals_get_work_items?) or the shape/source of `body.formEntries`.

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 restates the tool name almost verbatim ('Answers the specified work item'), plus a raw REST endpoint path. An agent learns nothing about what 'answering' entails (submitting form entries to complete/approve an approval request) or how this differs from siblings such as approvals_reject_work_item or approvals_execute_action_on_approval_request.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance is provided. It does not say that answering is the affirmative counterpart to approvals_reject_work_item, nor that the work item should first be read via approvals_get_work_item_by_id.

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 this is a non-read-only, open-world, non-idempotent mutation. The description adds no additional behavioral context such as required permissions, the effect of CANCEL, or the difference between fullApproval and currentLevelApproval.

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 brief and front-loads the core action, but the included endpoint path largely duplicates the annotation title and does not help tool selection. There is little waste, but also little structure beyond two short lines.

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?

This is a nested mutation tool with several action options and no output schema. The description does not explain the supported actions beyond approve/reject, omits CANCEL despite it being in the schema, and does not help distinguish full approval from current-level approval.

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 input schema already documents all parameters and nested fields. The description adds no further parameter semantics beyond the high-level approve/reject action, which is the expected baseline when the schema is comprehensive.

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

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

The description states a specific action and resource: approving or rejecting an approval request. It is clearer than the generic tool name, but it does not distinguish this action tool from sibling tools such as approvals_reject_work_item and approvals_answer_work_item.

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

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

The description provides no explicit guidance on when to use this tool versus the other approval-related sibling tools. It only restates the action and endpoint, leaving the agent to infer the appropriate 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 this is read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavior beyond that by explaining the default-to-latest-version behavior when apiVersion is omitted and showing the endpoint path. It does not discuss auth or rate limits, but those are less critical here.

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 information is front-loaded, but the description is somewhat rambling and includes a confusing example with both a /approvals?apiVersion=... path and a separate /about path. It is reasonably short overall, yet not every sentence is tightly organized.

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

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

For a simple read-only metadata endpoint with no required parameters, no output schema, and annotations covering safety, the description is largely complete: it states what the page contains and how apiVersion affects the response. It could be slightly clearer about the response format, but an agent has enough 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 schema already documents the single apiVersion parameter. The description still adds value by stating that the parameter is optional but highly recommended, that omitting it calls the latest supported API version, and by giving an example date-formatted value.

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

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

The opening 'Get about page' is generic and mostly restates the tool name/title. The second sentence clarifies that it returns supported and latest API version information, but the description never says this is the approvals API about endpoint or distinguishes it from the many sibling get_about 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?

Usage is implied: call this to discover supported API versions. The description gives useful guidance that apiVersion is optional but highly recommended and that omitting it defaults to the latest supported version, but it does not state when to use this versus sibling about endpoints or any prerequisites.

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

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

The annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds only the raw endpoint path "GET /approval/api/approvals", with no note on pagination defaults, search behavior, or whether filterEntitledRequests changes the result 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?

Two short lines with the verb-resource statement front-loaded, so there is no waste. But the terseness comes at the cost of usefulness rather than from efficient information packing.

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?

Eight parameters, no required fields, no output schema, and a broad search/filter surface: an agent needs guidance on paging, default sort, and how the two approval-state filters interact. None of that is present, so the definition is not sufficient on its own.

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 75%, close to the high-coverage baseline, so the schema does most of the work. The description contributes nothing about the two undocumented enum filters (requestState, approverState) or about paging semantics, so it neither helps nor hurts beyond baseline.

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

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

"Returns approval requests" restates the tool name with no added specificity. It does not distinguish this collection endpoint from close siblings such as approvals_get_work_items, approvals_get_approval_request_v3 or approvals_get_work_items_for_deployment.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer for a single request versus a list. The agent is left to infer everything from the name and parameters.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is fully covered without the description. The description adds only the raw GET path, which restates the annotation title rather than adding behavioral context such as error behavior for missing/invalid ids; this is minimum viable given the annotation coverage.

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

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

Two very short lines, front-loaded with the purpose, so the signal comes first. The second line duplicating the endpoint path is largely redundant with the annotation title but costs almost nothing.

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

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

For a simple read-by-id tool the schema and annotations carry most of the burden, but with no output schema the description says nothing about what 'details' are returned or what the response shape looks like. It is adequate to call the tool but leaves the agent guessing about the return payload.

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

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

Schema description coverage is 100%, with both 'id' (uuid, path) and 'apiVersion' (yyyy-MM-dd versioning) documented in the schema itself. The description adds no syntax or format guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Returns details of the approval request') and echoes the endpoint path, so the agent knows this is a single-record read. It does not distinguish itself from close siblings such as approvals_get_approval_requests_v3 (list) or approvals_get_work_item_by_id, leaving the agent to infer which one to pick.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named despite several similar retrieval tools in the sibling list. The agent must infer usage purely from the fact that a single 'id' path parameter is required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is provided structurally. The description adds no behavioral context beyond the endpoint, such as scope, auth expectations, or return characteristics.

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?

It is short, but the second line is an exact duplication of the first and neither line is written for an agent to read quickly. The space is not used to front-load meaningful purpose or usage 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?

Although the tool is simple and annotations are rich, the description does not explain what approval user groups are, whose groups are returned, or how this differs from related identity tools. An agent must infer too much from the name and endpoint alone.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool applies; the description neither helps nor harms 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?

The description is just the HTTP endpoint path, repeated twice. It conveys a GET on userGroups but adds no plain-language statement of what the tool returns or why it exists, so it largely restates the tool name/endpoint rather than clarifying purpose.

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

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

There is no guidance on when to use this tool, when not to use it, or which sibling tool is the alternative. The repeated endpoint path provides no selection criteria for an agent choosing among many identity and approvals tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what a work item represents, whether the id is scoped to a user/tenant, or what happens on an unknown id (404 vs empty).

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

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

Two short lines, front-loaded with the verb, so it is easy to scan. However, the second line is a raw endpoint path that mostly duplicates the name and annotation title rather than adding information.

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

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

For a simple read there is no output schema, so the description should say something about what is returned (work item type, state, approval request linkage) and clarify the undocumented 'expand' parameter. Neither is present, leaving the agent with only annotations and the name.

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

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

Schema coverage is only 50%: 'id' is tagged merely as '(path)' with a uuid format, and 'expand' has no description in either the schema or the description. The description reinforces that the id identifies the item but gives no hint about what 'expand' expands or what values it accepts.

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: retrieve a single work item identified by its id. The 'by id' phrasing implicitly separates it from the listing siblings such as approvals_get_work_items and approvals_get_work_items_for_deployment, though no sibling is named.

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

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

There is no guidance on when to use this tool versus the list endpoints or the deployment-scoped variants. The agent must infer that this is the single-item fetch from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds almost nothing on top: no pagination defaults, no ordering behavior, no indication of what a work item contains or whether unanswered items dominate results. The raw path string "GET /workitem/api/workitems" is the only extra content and carries no behavioral meaning.

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

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

Two short lines, purpose front-loaded, no filler prose. The trailing raw endpoint path duplicates the annotation title and could be dropped, but the overall size is 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?

A seven-parameter paginated list endpoint with no output schema needs the description to say what comes back and how paging/filtering behaves; it does neither. Given the absence of an output schema and only partial parameter documentation, the definition leaves an agent under-equipped 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 only 57% (type, state and assigneeState have no prose, only enums), and the description mentions no parameters at all. It does not explain that page/size control paging, that search covers deploymentName/work item name/workflow details, or how state and assigneeState interact — leaving the agent to read the schema cold.

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 ("Returns work items") plus the scope ("for the logged in user"), which is enough to separate it from approvals_get_work_item_by_id and approvals_get_work_items_for_deployment. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance, no mention of the deployment-scoped and by-id siblings, and no explanation of when to apply the state/assigneeState filters versus when to call a different endpoint. The only hint is the implicit "logged in user" scope.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description restates the endpoint and says nothing additional about pagination defaults, result limits, or whether 'all' conflicts with the paging parameters.

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

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

A single short, front-loaded sentence with the endpoint appended; no wasted prose. The raw path is somewhat redundant with the annotation title but is brief.

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

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

For a tool with 8 parameters, no output schema, and half the parameters undocumented, the description is too thin. It does not explain what a work item contains, how the type/state/expand filters behave, or how results are paginated.

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

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

With 8 parameters at 50% schema description coverage, several properties (ids, type, state, expand) have no documentation anywhere. The description only echoes deploymentId from the path and adds no meaning about filtering, expansion, or how page/size interact with 'all'.

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

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

States a specific verb and resource ('Returns all work items for a deployment') and the path makes the scope concrete. It does not distinguish itself from the nearby siblings approvals_get_work_items or approvals_get_work_items_for_deployment_request, so an agent must infer the difference.

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

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

There is no statement of when to use this versus the generic approvals_get_work_items or the deployment-request variant. The only clue is the path containing deploymentId, which is left implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the raw HTTP path – no notes on result set size, pagination defaults, or what 'work items' contain here versus the unfiltered endpoint.

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

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

Two lines, front-loaded, no filler – but the second line merely restates the endpoint path an agent gains little from. Conciseness is fine; the brevity here reflects under-specification rather than discipline.

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

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

For a read-only filtered list tool with no output schema, the description is too thin: nine parameters, 56% schema coverage, and several ambiguous ones (ids vs. deploymentId/requestId, expand) are left unexplained. An agent can invoke it but may misuse the filters.

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

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

Schema coverage is only 56%; nine parameters exist and the description only indicates that deploymentId and requestId come from the path. It says nothing about ids, type (enum MUI), state (ACTIVE/ANSWERED/REJECTED/EXPIRED), expand, or the paging parameters, leaving half the parameters undocumented in both schema and 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 ('Returns work items for a deployment request') and the path template makes the deploymentId/requestId scoping explicit. It doesn't however name or distinguish itself from the very close siblings approvals_get_work_items and approvals_get_work_items_for_deployment, which an agent could easily confuse with it.

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

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

There is no guidance on when to use this versus approvals_get_work_items, approvals_get_work_items_for_deployment, or approvals_get_work_item_by_id. The description is purely a restatement of the endpoint with no usage context or exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the REST path, which merely restates the annotation title: no word on resulting state transitions, whether the rejection is reversible, whether a reason/formEntries payload is mandatory, or what permissions are required.

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

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

Two short lines with the action front-loaded. The second line is a raw POST path that duplicates the annotation title and earns little space, but the definition is not bloated.

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 mutation in an approval workflow with a nested request body and no output schema, the description omits the essentials: what rejection does to the work item/approval request, whether the body is required content, and what the caller gets back. An agent could invoke it but not predict its effects.

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 nominally 100%, so the baseline is 3, but the schema descriptions are vacuous ('(path)' and 'Request body') and the nested formEntries object is entirely unexplained. The description does nothing to clarify that the body carries rejection form data, so it neither helps nor hurts relative 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 ('Rejects the specified work item'), which is more informative than the name alone. However, it does not differentiate itself from siblings such as approvals_answer_work_item or approvals_execute_action_on_approval_request, which plausibly also act on work items.

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

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

No guidance on when to reject versus using approvals_answer_work_item or approvals_execute_action_on_approval_request, and no prerequisites (e.g., approver role, work item state). The agent must infer the entire selection logic from the tool name.

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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description adds only the HTTP endpoint and does not explain the effect of cancellation, whether it is asynchronous, what state the request enters, or any auth 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 very short and front-loads the action before the endpoint, with no wasted prose. It is slightly under-specified rather than verbose, but structurally it is efficient.

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

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

For a mutation action with no output schema, the description should explain what cancellation actually does and any conditions around it. It leaves the agent with only the endpoint and verb, which is not enough to understand the operation's consequences or edge cases.

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

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

Schema description coverage is 100%, so requestId and apiVersion are already documented in the input schema. The description adds no parameter meaning, but the baseline is 3 when the schema fully carries 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 clear verb, 'Cancel', and the endpoint path ties it to blueprint request cancellation. It does not explicitly distinguish this action from sibling tools like blueprint_delete_blueprint_request or blueprint_get_blueprint_request, but the core purpose is identifiable.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no note about when a blueprint request is cancellable. The agent can infer it is for cancellation, but nothing tells it whether to choose cancel over delete or another request-management 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say whether a version is auto-created, whether content YAML must be valid first, what permissions or project scope are required, or what happens on duplicate names.

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?

It is short and front-loads the action, but the second line ('POST /blueprint/api/blueprints') merely restates the annotation title and adds no decision-relevant information for an agent.

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 nested-body mutation tool with no output schema, the description omits what the caller gets back (e.g., created blueprint id), whether the new blueprint is a draft or released, and how it relates to version/mapping creation flows. The rich schema covers inputs, but the operational context is missing.

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

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

Schema description coverage is 100%, so the nested body fields (name, content, projectId, organizationSharings, requestScopeOrg) are already documented in the schema. The description contributes no additional meaning about required combinations or field interactions, so the baseline 3 applies.

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

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

The verb+resource pair is explicit: 'Creates a blueprint.' However, it does not distinguish itself from close siblings such as blueprint_create_blueprint_from_mapping, blueprint_create_blueprint_version, or blueprint_update_blueprint, so an agent cannot tell from the description alone which creation path applies.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative creation tools in the sibling set. The only extra text is the raw endpoint path, which conveys nothing about selection criteria.

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

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

Annotations already declare this as a non-read-only, open-world, non-idempotent write operation, so the description needn't repeat that. It adds minor context about the source of the configuration but does not describe side effects, permissions required, or what happens on success/failure.

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

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

The purpose is front-loaded in the first sentence, but the second sentence merely repeats the endpoint already present in the title and annotations. That repetition does not earn its place, 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?

With no output schema, the description should ideally explain return values or key behavioral outcomes, which it does not. It provides the minimal context needed to understand the operation but leaves gaps about return values and error behavior given the nested request body.

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 fully documents both parameters (body and apiVersion). The description offers no additional parameter-level detail beyond the schema, making the baseline score of 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 ("Creates") and resource ("a blueprint from a Terraform blueprint configuration"). The parenthetical source endpoint distinguishes it from sibling tools like blueprint_create_blueprint, though it stops short of naming the mapping tool directly.

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

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

The phrase "obtained from /create-blueprint-mapping" implies a prerequisite workflow step, but the description does not explicitly say when to use this tool versus alternatives or state any exclusions. The usage context is present but must be 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, but the description frames the operation as retrieving/parsing and returning information. That reads as a read-only operation and omits the side effects implied by creating a blueprint mapping, contradicting the mutation annotation.

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

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

The description is short and front-loads the action, but the second line is a raw endpoint path that does not help an agent decide when to call the tool. The first sentence is also misleading about the mutation, so the structure is efficient but not fully effective.

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 nested-body, non-read-only integration endpoint with no output schema, the description does not explain the result, side effects, or usage conditions. The schema is complete, but the behavioral and routing context needed for safe 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%: repositoryId, commitId, sourceDirectory, and apiVersion are all documented in the schema. The description adds no parameter-level semantics beyond 'specified Terraform configuration file(s),' 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?

The sentence names a specific action and resource: retrieving and parsing Terraform configuration files for blueprint construction. However, it does not describe creating a blueprint mapping as the tool name and endpoint imply, and it does not differentiate from siblings like blueprint_create_blueprint_from_mapping or blueprint_get_terraform_configuration_sources.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named. The phrase 'for blueprint construction' is too vague to help an agent choose between this tool and the many other blueprint_* siblings.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety baseline is covered. The description adds nothing beyond the endpoint path: it does not say the call is asynchronous and returns a request to poll, mention plan/simulate/destroy flag interplay, or note that the optional destroy flag can tear down an existing deployment despite 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?

It is very short and front-loaded, but that brevity comes from omission rather than discipline; the second line is a raw REST path that duplicates the annotation title "POST /blueprint/api/blueprint-requests" and adds no 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 create/mutation tool with a deeply nested body, no output schema, and an async execution model, the description should explain the returned request identifier and how to follow up (get_blueprint_request, get_blueprint_request_execution). None of that is present, so an agent cannot infer the post-call workflow.

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 the nested body fields with their own explanations of plan, simulate, destroy, and mutual-exclusion rules, so the schema does the heavy lifting. The description adds no additional semantics, which is the baseline-3 case.

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?

"Creates a blueprint request" states a verb and a resource, but it essentially restates the tool name plus the raw endpoint path. It gives no indication of what a blueprint request actually is (an execution/plan of a blueprint) or how it differs from close siblings like blueprint_create_blueprint, blueprint_create_blueprint_version, or blueprint_validate_blueprint.

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

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

There is no when-to-use guidance at all: nothing says to call this rather than blueprint_create_blueprint, blueprint_validate_blueprint, or catalog_request_catalog_item_instances, and no mention of prerequisites such as a released blueprint version being required.

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, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating that it creates something and the endpoint path — it does not say whether the new version starts in released state or unreleased, whether it requires the blueprint to be validated first, or how it interacts with the release/unrelease tools.

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

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

Two short lines, front-loaded with the action, with no filler. The inclusion of a raw POST path adds little for an agent but is not wasteful enough to penalize heavily.

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

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

For a mutation tool that creates a new version object with a nested body containing release and sourceControlPush flags, the description omits the meaningful outcomes an agent needs: resulting version state, effect of release=true versus a separate release call, and source control push behavior. With no output schema, that gap is not filled anywhere else.

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 descriptions for version, release, changeLog, description, and sourceControlPush, so the schema carries parameter semantics. The description contributes no additional parameter meaning, which is acceptable but not additive; 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: creates a blueprint version for a given blueprint ID, which distinguishes it from get/list counterparts. It does not differentiate from the closely related siblings blueprint_release_blueprint_version or blueprint_restore_blueprint_version, so an agent must infer which mutating tool to pick.

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

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

No guidance on when to use this versus blueprint_release_blueprint_version, blueprint_restore_blueprint_version, or blueprint_update_blueprint, and no stated prerequisites (existing blueprint, required permissions). The only context is the raw REST path, which is schema-level information rather than 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds nothing beyond restating the write operation — no mention of required authorization, uniqueness constraints on name, or what happens on conflict. It does not contradict 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?

Very short and front-loaded with the verb and resource. The trailing 'POST /properties/api/property-groups' duplicates the annotation title and adds little, but overall there is no bloat.

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?

This is a creation tool with a deeply nested body (properties map with recursive type definitions) and no output schema. The description never explains what the request body must contain, what INPUT vs CONSTANT types mean, or what the response returns (e.g., the created group ID), leaving significant gaps for a complex mutation.

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 nested property definitions, so the schema carries parameter meaning fully. The description contributes no additional detail on the body structure or the meaning of the apiVersion parameter, which is the correct baseline-3 case.

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 ('Creates a property group'), which distinguishes it from blueprint_update_property_group, blueprint_delete_property_group and blueprint_list_property_groups by name alone. It does not explicitly contrast with those siblings in the text, so it stops short of a 5.

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

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

There is no guidance on when to create a property group versus updating an existing one, no prerequisites (project selection, permissions), and no mention of the alternative sibling tools. The agent must infer all usage context from the tool name and annotations.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false. The description adds nothing beyond that: it does not warn that repeated POSTs create duplicate versions (non-idempotent), what happens if the version string already exists, or that url/authenticationType govern an outbound download.

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?

Very short and front-loaded, with no wasted prose, but the brevity is under-specification rather than economy. The duplicated raw HTTP route is the only structural content beyond a one-line verb phrase.

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?

This is a mutation tool with a nested body object, no output schema, and non-idempotent semantics, yet the description says nothing about the returned version object, duplicate handling, or required download/auth configuration. For this complexity level, the definition is materially incomplete.

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 two top-level parameters and the eight nested body fields (url, version, sha256Checksum, authenticationType, credentials, enabled) are self-documented. The description contributes no additional parameter meaning, which is acceptable given 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?

"Creates a version" essentially restates the name (create + terraform_version); only the bare POST route adds the fact that this is a Terraform version integration record. It draws no distinction from close siblings such as blueprint_create_blueprint_version, blueprint_update_terraform_version, or blueprint_list_terraform_versions.

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

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

No indication of when to create a new version versus updating an existing one, and no prerequisites (the version must presumably be a Terraform release with a downloadable binary URL). The agent is left to infer everything from the name and the HTTP route.

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 cover critical behavioral traits (destructiveHint, readOnlyHint, idempotentHint). The description adds the REST endpoint structure, which is contextually useful but does not disclose new behavioral constraints or limits beyond the structured data.

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

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

The definition is highly concise, front-loading the action and providing the resource identifier structure in a clear, single-line manner.

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?

While the endpoint structure is helpful, the definition is not complete for an agent making a choice between the raw API call and the wrapped onboarding function. It lacks context on why one would choose this over the other.

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?

Since schema description coverage is 100%, the schema already details the purpose of `blueprintId` and `apiVersion`. The description merely restates the parameter's role within the URL path.

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

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

The description clearly states the action (Deletes a blueprint) and provides the specific HTTP method and URL structure (DELETE /blueprint/api/blueprints/{blueprintId}), making it highly distinguishable from other potential 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?

While the API route implies a specific implementation style, the description fails to distinguish when this specific tool should be used versus the similar onboarding tool, onboarding_delete_blueprint_by_id, which exists in the sibling list.

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 nothing beyond that — no statement of what is destroyed, whether a running/final-stage request can be removed, or what happens when 'force' is used on a non-final-stage 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?

Very short with no filler, but the second line merely restates the HTTP route already encoded in the tool name and schema path parameter. The wording that would actually help an agent choose this tool is absent while a redundant line is present.

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

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

This is a destructive, single-required-parameter operation, and the annotations plus the fully described schema carry the safety profile and parameter semantics. What the description lacks is usage routing rather than missing mechanics, so for its complexity level it is close to sufficient.

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

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

Schema description coverage is 100%: requestId (path), force ('Force delete if not in final stage'), and apiVersion are all documented in the schema. The description adds no parameter meaning, so the baseline 3 applies — the schema, not the prose, does the work.

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 verb+resource ('Deletes request') plus the raw path make it clear this removes a blueprint request by ID, so the basic operation is identifiable. But there is no differentiation from closely related siblings such as blueprint_cancel_blueprint_request or blueprint_delete_blueprint — an agent must guess which removal semantic applies.

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 offers no when-to-use or when-not-to-use guidance. It never mentions the cancel_blueprint_request alternative, nor when the 'force' flag is appropriate, leaving the agent to infer the choice of tool from the resource path alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the underlying HTTP route (DELETE /properties/api/property-groups/{propertyGroupId}), not what else is affected — e.g. whether consumers of the group are detached or broken. Useful context, but thin for a destructive 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?

One front-loaded sentence plus the endpoint line — no filler prose. The REST route largely duplicates what the annotations' title already convey, so it is marginally redundant rather than harmful.

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 delete with no output schema, the basic shape of the call is fully conveyed by the schema and annotations. What is missing is consequence information: what a deleted property group orphans, and whether the call fails on in-use groups — the pieces an agent would need to act 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%, with propertyGroupId typed as uuid and marked '(path)', and apiVersion documented in the schema. The description adds no semantics beyond the route template that echoes the same parameter, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Deletes a property group'), which distinguishes it from the sibling read/update operations (blueprint_get_property_group, blueprint_update_property_group, blueprint_list_property_groups). It does not explicitly name those siblings as alternatives, but the operation is unambiguous on its own.

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

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

There is no guidance on when to use this versus alternatives, no statement of prerequisites (ownership/permissions), and no caution that deletion is irreversible or that a group still referenced by blueprints may fail. The agent must infer all usage context from the name alone.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond restating the operation and endpoint; it does not mention permanence, impact on dependent blueprints, or any side effects.

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 with the action. The second line, an HTTP endpoint path, largely repeats the annotation title and is not especially informative, but the overall text is not verbose.

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

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

For a simple delete operation with complete parameter schema coverage and strong annotations, the description is minimally sufficient for invocation. However, it omits meaningful context such as whether deletion is irreversible, whether versions in use can be deleted, or any dependency on blueprints referencing the version.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no additional meaning about versionId or apiVersion beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Deletes a terraform version'. The HTTP DELETE path reinforces the operation. It does not explicitly differentiate itself from siblings like blueprint_get_terraform_version or blueprint_update_terraform_version, but the action and resource are clear.

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

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

There is no guidance on when to use this tool versus alternatives such as updating, listing, or retrieving Terraform versions. No prerequisites or warnings are provided, aside from the implicit meaning of '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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely new context: it names the required privilege (assembler admin in VM Apps Org) and describes the payload (supported and latest API versions). It stops short of return structure or failure modes, which keeps it out of the top band.

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 statement is front-loaded, but the body trails off into generic REST documentation ('Here is an example of a call...') and raw endpoint URLs that add little for an MCP caller. The important access restriction is buried mid-paragraph rather than surfaced.

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

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

For a zero-parameter read tool with no output schema, describing the returned content and the access requirement is the right coverage, and it does that. However, the misleading version-parameter discussion leaves ambiguity about what the tool actually returns and whether arguments are accepted, which undermines completeness.

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

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

Zero parameters, so the schema baseline would be 4, but the description actively invents a 'version parameter' that does not exist in the input schema (which is an empty object with additionalProperties=false). The apiVersion example refers to the underlying REST URL, not to any MCP argument, so an agent reading this may attempt to pass an argument the tool cannot accept.

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 ('Returns blueprint API information') and then narrows to what the page contains: supported API versions and the latest version. An agent can distinguish it from blueprint_get_blueprint or blueprint_list_blueprints because it clearly reads as an endpoints/version discovery call, though it never names those siblings explicitly.

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

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

It hints at the reason to call it ('version parameter is optional but highly recommended' before issuing other blueprint calls) and adds an access gate ('Only assembler admin in VM Apps Org can access'). It does not state explicitly when to prefer this over sibling tools or what to do if access is denied, so usage remains implied rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds almost no behavioral context beyond the endpoint: it does not explain what blueprint details are returned, how revalidate behaves, or any auth/caching considerations.

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 brief and front-loaded, with no wasted prose. The endpoint path is somewhat redundant with the tool name and annotation title, but the overall structure is compact and readable.

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 rich schema descriptions and annotations, the definition is minimally adequate for invocation. However, it does not explain what 'blueprint details' contains, and since there is no output schema, an agent has little context about the response shape or how revalidate/select affect 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 the input schema already explains all four parameters. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline case for high schema coverage.

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

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

The description states a specific verb and resource: 'Returns blueprint details.' This is clear enough to distinguish a read operation from create/update/delete siblings. However, it does not differentiate this tool from closely related read siblings such as blueprint_get_blueprint_version, blueprint_get_blueprint_request, or blueprint_get_blueprint_resources_plan.

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

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

The description gives no guidance on when to use this tool versus alternatives. It merely states the operation and HTTP endpoint, leaving the agent to infer whether it should call this or one of the many other blueprint-related retrieval tools.

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