Pipefork Management MCP

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds the useful auth/scope context that creation happens in the authenticated caller's workspace, but says nothing about idempotency, slug collision behavior, or side effects. With annotations carrying the main burden, this is an adequate-but-thin 3.

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

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

A single front-loaded sentence with no filler or redundancy. It is structurally clean, though its brevity reflects under-specification rather than genuine economy.

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

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

An output schema exists, so return values need not be explained, but for a creation tool with three undocumented parameters the description omits uniqueness constraints, error/conflict behavior, and any hint of what a created API contains. The agent has the bare minimum needed to attempt the call and little 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 0% across 3 parameters, so the description is the only place parameter meaning could be added, and it mentions none of name, slug, or description. The schema does encode that name is required and slug has a strict pattern, but the description adds zero semantic value on top of it.

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

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

The description gives a specific verb and resource ('Create an API') and adds the scope 'in the authenticated caller workspace'. It is clearly distinguishable from siblings like api_get/api_list and from the other *_create tools (connection_create, endpoint_create, secret_create). It stops short of any explicit sibling routing, but the resource 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 when-to-use, when-not-to-use, or alternative guidance. The agent is told the workspace context but nothing about prerequisites (e.g., whether the workspace must already exist, whether slug must be unique) or when another tool is more 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds no further behavior such as error handling for unknown IDs or permission requirements, leaving it as pure restatement of the read semantics.

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 sentence with the operation and the lookup key front-loaded. Nothing redundant and nothing padded.

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

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

An output schema exists, so return values need not be described. For a one-parameter read tool whose parameter is completely undocumented in the schema, the description should say more about what the stable API ID is and what happens on a miss; as written it is minimally adequate.

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 description coverage is 0% for the single apiId parameter, so the description must compensate. Saying 'stable API ID' is a useful hint that the identifier is the stable ID rather than a name or version-specific ID, but it gives no format, example, or lookup guidance.

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 (Get) and resource (API) with singular scope, which implicitly separates it from sibling api_list and api_create. It is clear on its own, but it never names a sibling or any scoping condition to distinguish itself explicitly.

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

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

Usage is only implied: an agent infers it should call this when it already holds an API ID and wants a single record, and call api_list otherwise. No explicit when-to-use, prerequisite, or failure guidance is 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact — results are permission-filtered to the authenticated caller in the current workspace — but says nothing about pagination, result limits, or whether archived APIs are included by default.

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

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

A single front-loaded sentence with zero filler; every clause (access scope, workspace scope) carries information an agent needs.

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

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

An output schema exists, so return-value documentation is unnecessary, and the read-only annotations cover safety. However, for a listing tool the omission of the mode/default behavior and any pagination expectation leaves a real gap.

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

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

Schema description coverage is 0% and the description never mentions the single `mode` parameter, its 'active'/'archived' enum, or the 'active' default. The agent must infer that archived APIs are excluded unless mode is set.

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

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

States a specific verb and resource ('List APIs') plus two scoping qualifiers: caller access rights and current workspace. That distinguishes it in kind from api_get and api_create, though no sibling is named explicitly.

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

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

There is no statement of when to use this versus alternatives such as api_get, and no exclusions or prerequisites beyond the implicit 'may access' filter. Usage is only inferable from the verb '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 readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavior note — authentication is supplied via auth-profile references rather than inline secrets — but 'safe configuration' is vague, and nothing is said about uniqueness of name, idempotency, or failure modes.

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

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

One front-loaded sentence with no padding or repetition. It is efficient, though the brevity is partly under-specification rather than disciplined concision.

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

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

An output schema exists so return values need not be described, but for a creation tool with 7 parameters, three required, nested per-environment objects, and zero schema descriptions, the definition leaves too much unexplained to invoke it confidently. The critical concept — that base URLs and auth profiles are keyed by environment — is never surfaced.

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

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

Schema description coverage is 0% across 7 parameters, including nested environment-keyed maps and the runtimeKind enum, yet the description only obliquely hints at authProfileIdByEnvironment via 'auth-profile references'. It does not explain the environment-key map semantics, the http/llm runtime distinction, or the optional llmProviderConfigIdByEnvironment, so it fails to compensate for the documentation gap.

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

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

The description states a specific verb and resource ('Create an upstream connection'), which is distinct from connection_get, connection_list, and connection_update. However, it offers no explicit sibling differentiation beyond the verb, and 'upstream connection' is left unpacked for an agent unfamiliar with the domain.

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 versus update an existing connection, no prerequisites (e.g., that an auth profile must exist first), and no mention of alternatives such as api_create or endpoint_create. The agent is left to infer context 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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the description's bar is lower. It still adds meaningful behavior: 'safe metadata' signals that sensitive fields (e.g. credentials/secrets) are redacted from the response, and it scopes the lookup to the authorized workspace.

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 sentence, front-loaded with the verb and resource, with zero filler. Nothing to trim.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers only what structured data cannot: that the returned metadata is sanitized and workspace-scoped.

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

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

Schema description coverage is 0% and the single 'id' parameter has no description anywhere, so the description could clarify whether this is a connection ID, slug, or name. 'One upstream connection' only weakly implies the parameter identifies a connection; baseline 3 for a sparse single-param 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?

Specific verb+resource: 'Get safe metadata for one upstream connection.' The word 'one' distinguishes it from the sibling connection_list without naming it explicitly. Siblings connection_create/connection_update are clearly different operations, so differentiation is implied 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 when-to-use or when-not-to-use guidance is provided, and no alternative is named. The phrase 'in the authorized workspace' hints at scope but does not tell the agent when to prefer this over connection_list or how to obtain a valid 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=true and destructiveHint=false, so safety is covered. The description adds real behavioral value by scoping the payload to 'safe metadata', signaling that credentials/sensitive fields are filtered out, and by restricting results to the 'authorized workspace'.

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

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

A single front-loaded sentence with no filler; every clause (list, safe metadata, connections, authorized workspace) carries information an agent needs.

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

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

With an output schema present, return format needn't be described, and annotations cover the safety profile. The only minor gap is whether results are paginated or bounded, which is left 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?

The tool takes zero parameters, so there is no per-parameter semantics to document and the baseline is 4. The description correctly avoids inventing filter arguments that the schema does not 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 ('List') and resource ('upstream connections') with scope ('authorized workspace'), which cleanly separates it from the singular connection_get and the mutating connection_create/connection_update. It does not name those siblings explicitly, so it lands just short of 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?

'List' implies the enumerate-everything case versus connection_get for a single record, but the description never states when to prefer this over connection_get or what the authorized-workspace constraint excludes. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds one piece of real context — that auth is supplied via profile references rather than raw secrets — but it never explains what a destructive update overwrites, whether omitted fields are cleared or preserved, or whether the change is reversible.

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

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

A single front-loaded sentence with no filler; the verb and resource lead. It is efficient, though arguably under-sized for an 8-parameter destructive mutation.

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

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

An output schema exists, so return values need no explanation, but for a destructive 8-parameter update with zero schema descriptions the description leaves the agent without field semantics, merge/replace behavior, or side-effect detail. It is too thin for this tool's complexity.

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

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

Schema description coverage is 0% across 8 parameters, including nested maps (baseUrlByEnvironment, authProfileIdByEnvironment, llmProviderConfigIdByEnvironment) and an enum (runtimeKind). The description's phrase "auth-profile references" loosely gestures at two of them but says nothing about id, name, description, runtimeKind, or defaultHeaders, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb+resource ("Update an upstream connection") and the sibling verbs (create/get/list) make the operation unambiguous. However, it does not differentiate itself from connection_create beyond the verb, and the trailing phrase "using safe configuration and auth-profile references" is fuzzy rather than scoping.

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 connection_create, connection_get, or connection_list, and no statement of preconditions (e.g. the connection must already exist, or that this replaces rather than merges fields). The agent must infer all routing 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=false and destructiveHint=true, so the write/destructive nature is covered. The description adds the source (current draft) and target (Dev) but says nothing about what the deploy overwrites, whether a prior dev deployment is replaced, or any prerequisite validation - the details an agent needs for a destructive operation.

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

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

A single front-loaded sentence with zero filler; the verb, source and target all appear immediately.

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

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

An output schema exists so return values need not be explained, but for a destructive two-parameter tool the definition omits parameter meaning, prerequisites, and the consequences of overwriting the Dev deployment. It is too thin to safely invoke.

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

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

Schema description coverage is 0%, so the description carries the full burden for apiId and changelog. It alludes to the draft implicitly but never explains apiId (the API to deploy) or what changelog is for, leaving both parameters undocumented anywhere.

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

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

States a specific verb (Deploy), source (the current draft) and target (Dev environment), which lets an agent separate it from deployment_promote and deployment_rollback. It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. With siblings like draft_validate, deployment_promote and deployment_rollback present, an agent gets no signal about whether validation must precede deployment or when to promote instead of deploy.

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, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered. The description adds the return content (environments, rollback targets), which is useful, but that overlaps with the existing output schema and adds little behavioral context. Appropriate baseline for an annotated read tool.

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

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

A single efficient sentence that is front-loaded with the verb and resource, and appends the scope detail without 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 one-parameter read tool, the description plus rich annotations and an output schema cover most of what an agent needs. The remaining gap is the missing explanation of the apiId parameter and any usage routing against deployment siblings.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single 'apiId' parameter. It only implies the parameter via 'for an API', offering no format, identifier type, or constraints. Partial compensation, but the gap remains.

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 ('Get full deployment state') and adds scope detail ('including environments and rollback targets for an API'), so the agent knows this returns current deployment configuration rather than history. It does not explicitly distinguish itself from siblings like deployment_history or deployment_list, keeping it 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 when-to-use guidance and no routing to alternatives. With many sibling tools (deployment_history, deployment_list, deployment_promote, deployment_rollback), the agent gets no signal about which to pick for which situation. Usage is only implied by the phrase 'deployment state'.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no ordering, time-range, pagination, or volume characteristics for what could be a long history list.

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 sentence with no filler and the resource front-loaded. It is efficient, though the brevity borders on under-specification for a tool with an overlapping sibling.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. What is missing for a low-complexity list tool is routing context against deployment_list/deployment_get_state and any hint about ordering or result size.

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

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

Schema description coverage is 0%, so the description must carry the meaning, and it only implies that the parameter identifies an API ('for an API'). The parameter name apiId is self-describing and there is only one required param, so this is minimally adequate rather than informative.

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

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

States a specific verb and resource ('List deployment history') scoped to an API, so an agent knows it retrieves historical deployment records rather than current state. However, it offers no differentiation from siblings like deployment_list or deployment_get_state, which plausibly overlap with this surface.

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 prerequisites (e.g. the API must already exist), and no indication of when to prefer deployment_list or deployment_get_state instead. The agent must infer the choice 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the result pairs environments with their current states, and says nothing about pagination, result size, or whether undeployed environments appear.

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

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

A single front-loaded sentence with no filler — the verb and scoped resource come first and nothing is repeated from the name or annotations. It is efficient, though arguably too sparse given the sibling overlap it never resolves.

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

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

An output schema exists, so return-value shape need not be described and the required apiId is at least implied. Still, for a listing tool sitting beside deployment_get_state and deployment_history, the definition is thin on disambiguation and on whether 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?

Schema description coverage is 0% and apiId carries no description in the schema. The description supplies only the weak hint 'for an API', leaving the identifier's expected format (ID vs. slug/name) and whether it accepts an API version unstated.

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

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

Clear verb+resource: 'List deployment environments and their states for an API.' This distinguishes it from the mutation and history siblings (deployment_deploy, deployment_rollback, deployment_history). However, it does not differentiate itself from deployment_get_state, which by its name appears to return the same per-environment state information.

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 deployment_get_state (single-environment state) or deployment_history (past state changes). The agent must infer the boundary between listing all environments and fetching one environment's state from names 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 flag this as a non-read-only, destructive, closed-world mutation. The description adds the concrete transition model, which is useful context, but does not disclose what gets overwritten in the target environment, whether the promotion is reversible, or what the returned state looks like despite an output schema existing.

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

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

A single front-loaded sentence with zero filler; the parenthetical transition list is the only content and it directly serves parameter semantics.

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

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

Given a destructive mutation with an output schema, the description covers the what and the allowed transitions but omits operational context an agent needs: effect on the target environment, reversibility, and any confirmation requirements. Adequate but with clear gaps.

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

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

Schema coverage is 100% and the anyOf enforces the exact dev->test / test->prod pairs, so the schema fully documents parameters. The description only restates those transitions in prose without adding format or validation detail beyond the schema.

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

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

States a specific verb (Promote) and resource (a deployment version), and enumerates the exact environment transitions (Dev to Test, Test to Prod). This clearly distinguishes it from deployment_deploy, deployment_rollback, and deployment_undeploy.

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 usage context by naming the specific env transitions, but does not explicitly state when to use this versus deployment_deploy or deployment_rollback, nor any prerequisites such as the source environment needing an existing deployment.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is known. The description adds nothing beyond that: it does not say what is overwritten, whether the rollback is reversible, whether active traffic drops during the switch, or what authorization is required. For a destructive mutation, that is a substantial gap.

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

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

A single, front-loaded sentence with no filler, so it is structurally clean. It is too thin rather than too long, which keeps it from being an example of strong concise specification.

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?

Output schema exists so return values need no explanation, but for a destructive, three-required-parameter operation with zero schema coverage, the description leaves the agent without enough to invoke it confidently. It should identify the parameters' roles and the side effects of the rollback.

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

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

Schema description coverage is 0%, so the burden falls on the description, which mentions neither environmentName, versionId, nor apiId by name. It loosely implies an environment and a target version but omits apiId entirely and gives no format or enum context (dev/test/prod) beyond what the schema already declares.

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 (rollback) and resource (environment to a previous version), which is clearly distinguishable from generic siblings like api_get or secret_list. However, it does not differentiate itself from the closely related deployment_undeploy, deployment_promote, or deployment_deploy siblings, leaving the agent to infer the distinction.

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 roll back versus using deployment_undeploy, deployment_promote, or deployment_deploy. No prerequisites, no mention of required prior state (e.g., that a target version must already exist), and no exclusions 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 and readOnlyHint=false, so the safety profile is carried structurally. The phrase 'disabling it' does add value by implying the environment is deactivated rather than destroyed, but the description never says whether this is reversible, whether prod is protected, or what happens to in-flight traffic.

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 short sentence, front-loaded with the verb and object; nothing is padded or repeated from the schema. It is efficient, though the brevity shades into under-specification.

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

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

An output schema exists, so return values need no explanation, and annotations cover the destructive profile. Still missing for a prod-capable destructive mutation: prerequisites, reversibility, and how it differs from deployment_rollback.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. environmentName's enum (dev/test/prod) is visible in the schema, but the description never warns that undeploying 'prod' is a severe operation, nor does it explain the apiId/environmentName pairing.

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 (undeploy) and resource (an environment), which is clearly distinguishable from api_create, secret_rotate, or endpoint_delete in the sibling list. It does not, however, differentiate itself from the adjacent deployment_rollback or deployment_deploy, so the agent must guess at the relationship between those operations.

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

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

There is no when-to-use guidance, no prerequisites (must the environment currently be deployed?), and no mention of the obvious alternative deployment_rollback. The agent gets a definition but no routing logic.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The word 'current' hints that older/non-canonical drafts exist and are not returned, which is modest added value, but there is no mention of auth, caching, or error 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?

A single front-loaded sentence with no filler; the resource and the identifying key both appear immediately.

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

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

With an output schema present, return values need not be described, and annotations cover the safety profile, so the remaining burden is light. What is missing is routing guidance relative to draft_validate and apis_get, which an agent working among 26 siblings would benefit from.

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

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

Schema coverage is 0% and the schema only says the string must be non-empty, so the description must carry the meaning. 'By its stable API ID' usefully disambiguates from a draft ID or version ID, but gives no format or example of what a stable API ID looks like.

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 (Retrieve) and a specific resource (the current canonical draft for an API), which is distinct from apis_get and from draft_validate. It does not explicitly distinguish itself from siblings, but the draft/API split is inferable from the text.

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 statement, no prerequisite, and no reference to alternatives such as draft_validate or api_get. The only usage signal is the implicit read of the current draft, which is not enough to guide 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 declare this is a safe, non-destructive, closed-world read, so the safety profile is covered. The description adds the useful scoping detail that it acts on the *canonical* draft keyed by *stable* API ID, but it says nothing about what is checked, whether a failed validation is an error or a result, or side effects on the draft.

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 tightly-written sentence with the action, target, and lookup key all front-loaded. No filler and nothing to trim.

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

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

An output schema exists, so return values need not be described. However, for a validation tool the key missing context is what constitutes a valid/invalid draft and how that surfaces to the caller, which the description leaves entirely unexplained.

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

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

Schema coverage is 0%, so the schema does not document apiId at all. The description partially compensates by clarifying it is a 'stable API ID' (implying the immutable identifier rather than a name or version), but it does not state the expected format or where such an ID comes from.

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 (Validate) and resource (the current canonical draft for an API), plus the lookup key. It is distinguishable from siblings like draft_get, though it never explicitly contrasts itself with that tool or with api_get.

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 validate versus when to simply fetch the draft with draft_get, nor any mention of prerequisites (e.g., that a draft must exist) or what a validation run is meant to catch. The agent must infer the use case 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=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered structurally. The description adds only the scoping fact that the endpoint is created inside a draft; it says nothing about idempotency, whether endpointId must be unique, or what happens on collision. With annotations carrying the safety burden, this is minimum viable.

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 with no filler or redundancy. It is compact rather than bloated; the problem is under-specification, not wordiness.

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 6 parameters at 0% schema description coverage and no exclusions or prerequisites, the description is far too thin. The existing output schema spares it from explaining return values, but it still leaves parameter meaning and when-to-use entirely unaddressed.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining 6 parameters (endpointId, method, path, apiId, initialStepId, queryParameters) — and it mentions none of them, not even the required ones. The schema's enums and patterns give an agent structural hints, but the description contributes zero meaning beyond them.

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

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

States a specific verb+resource ("Create a structured endpoint") and scopes it to an API draft, so the agent knows what object is produced and where it lives. It does not, however, distinguish itself from siblings such as endpoint_update or step_create, which also mutate draft structure.

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

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

There is no statement of when to use this tool versus endpoint_update, step_create, or draft_validate, and no prerequisites (e.g., that the referenced draft must already exist). The only contextual clue is the phrase "in an API draft," which implies scope but not usage.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the 'API draft' scoping; it says nothing about irreversibility, whether child steps are removed, effects on published versions, or required permissions.

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

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

A single front-loaded sentence with the verb first and no filler. It is appropriately sized, though brevity here comes at the cost of the missing behavioral and parameter detail.

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

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

An output schema exists so return values need not be described, but for a destructive, two-param mutation with zero parameter documentation the definition should at least state the deletion scope and consequences. As written it is too thin for the operation's risk level.

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

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

Schema description coverage is 0% for both required parameters (apiId, endpointId). The description never mentions either parameter or clarifies that endpointId is scoped within apiId, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Delete a structured endpoint') plus the container it lives in ('from an API draft'), which distinguishes it from step_delete and secret_deactivate. It does not explicitly contrast with endpoint_create/endpoint_update, but the verb makes the distinction obvious.

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

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

No when-to-use guidance, no prerequisites (e.g., draft must exist, whether a published version blocks deletion), and no mention of alternatives such as endpoint_update for reversible changes. The agent is left to infer that this is the removal path for endpoints.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say whether this is a partial or full replace, whether omitted fields are cleared, what happens to existing agentTool/response configuration, or what errors to expect for a destructive 9-parameter 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?

A single front-loaded sentence with zero filler, which is efficient. But for a destructive tool with nine parameters including nested configuration objects, this size is under-specified rather than genuinely 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?

An output schema exists, so return values need not be explained, but for a destructive mutation with nine parameters and a required-vs-optional split (endpointId/apiId required, seven optional), the description omits update semantics, failure modes, and parameter mapping. It is not adequate to call this tool correctly and safely.

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

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

Schema description coverage is 0% across 9 parameters, and the description names none of them. Complex nested inputs like agentTool (toolName, inputSchema, outputSchema, errorSemantics) and response (mode/code/schema) are left entirely unexplained, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (update) and resource (structured endpoint) with scope (in an API draft), so an agent knows the target. It does not, however, distinguish itself from endpoint_create, endpoint_delete, or the step_* 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?

There is no when-to-use guidance, no prerequisites (e.g. draft must exist, endpointId must be valid), and no mention of alternatives such as endpoint_create for new endpoints. The phrase 'in an API draft' implies a context but leaves the agent to infer when this tool applies.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); they say nothing about data visibility. The description adds a genuinely important behavioral trait — 'Submitted values are never returned' — signalling a write-only secret that cannot be read back. It still omits collision/overwrite behavior and permission requirements, so not a 5.

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

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

Two sentences, no filler, and the operation is front-loaded before the non-obvious visibility constraint. 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?

An output schema exists, so return values need not be described, and the write-only note is a useful addition. However, with a nested environment-keyed values object and no parameter documentation anywhere, the description leaves an agent guessing about the core input shape.

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

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

Schema description coverage is 0% across 3 parameters, so the description carries the full burden and delivers nothing. The nested 'values' object keyed by dev/prod/test environments is the least obvious part of the contract and is never explained; neither is the optional 'description' field.

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

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

States a specific verb and resource ('Create a workspace secret'), which is immediately distinguishable from sibling reads and mutations like secret_list, secret_rotate, and secret_deactivate. It does not explicitly name or contrast with 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?

No when-to-use guidance and no mention of alternatives. An agent is not told whether to use this versus secret_rotate when a secret already exists, nor what happens on a duplicate 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 and readOnlyHint=false, so the mutation profile is covered. The description adds a genuinely useful behavior note — that secret values are not exposed — but says nothing about reversibility, effect on dependent connections, or required permissions.

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

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

A single front-loaded sentence with zero filler; the verb, scope, and the key non-exposure guarantee all land immediately.

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

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

An output schema exists, so return values need no explanation, and there is only one simple scalar parameter. However, for a destructive single-target mutation, the description could have stated whether deactivation is reversible or what happens to consumers of the 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 0% for the single 'name' parameter, and the description does not clarify that 'name' identifies the secret to deactivate. Only the indirect phrase 'one workspace secret' hints at the parameter's meaning, leaving the identifier semantics largely undocumented.

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

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

States a specific verb (deactivate) and resource (workspace secret), scoped to a single item via 'one'. It is distinguishable from siblings like secret_rotate or secret_create, though it doesn't explicitly name which sibling to prefer for related operations.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as secret_rotate or secret_delete. The agent must infer that deactivation is the soft-disable path from the verb 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior for this domain: only metadata is returned, not secret values, which tells the agent not to expect material it might otherwise assume.

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

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

One sentence, front-loaded with the verb and resource, zero filler. Nothing could be trimmed without losing scope information.

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

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

With no parameters, an output schema present, and annotations covering the safety profile, the description covers what an agent needs to select and invoke it. It is slightly thin on the scope of the listing (e.g., whether all workspace secrets are returned), but nothing critical is missing.

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

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

There are zero parameters and schema coverage is 100%, so per the rubric the baseline is 4. There is nothing parameter-related for the description to add or omit.

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

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

States a specific verb (List) and resource (metadata for secrets) and scopes it to the authenticated caller workspace. It indirectly separates itself from secret_create/rotate/deactivate by specifying metadata, but never names an alternative sibling, so differentiation is implied rather than 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?

Usage is implied by the verb-plus-resource framing, and the workspace scoping gives context, but there is no statement of when to use this versus secret_get-style siblings or any exclusions. An agent can infer the purpose but receives no routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the mutation/safety profile is covered. The description adds one genuinely useful fact beyond that – submitted values are write-only and never returned – but says nothing about whether the previous secret value is invalidated or destroyed by rotation.

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, front-loaded sentences with zero filler; the scope statement comes first and the behavioral caveat second.

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

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

An output schema exists so return values need not be described, but for a destructive rotation with two undocumented required parameters and a nested environment map, the description leaves too much unspecified to call it complete.

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

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

Schema description coverage is 0% and the description adds no parameter meaning at all. The nested 'values' object with dev/test/prod keys is particularly opaque: nothing explains whether all environments must be supplied, whether partial rotation is allowed, or how 'name' maps to an existing secret.

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 ('Rotate') and resource ('workspace secret') with a scope qualifier ('one'), which cleanly separates it from secret_create and secret_deactivate. It does not explicitly name a sibling to route against, 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?

There is no guidance on when to rotate versus create a new secret or deactivate one, nor any stated prerequisites (permissions, whether the secret must exist first). The agent must infer the appropriate 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?

Annotations already declare this is a non-read-only, non-destructive, non-open-world write, so the safety profile is covered. The description adds only the 'draft endpoint' target context and does not disclose the constraint that stepId/outputName uniqueness or the limited set of supported step types matter, nor anything about failure behavior for a complex 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?

A single front-loaded sentence with no filler or repetition. It is efficiently written but so terse that it cannot carry the information load the tool requires, so it is concise without being adequately informative.

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 step parameter is a deeply nested five-way discriminated union with zero field documentation, the description leaves an agent guessing at required shapes and legal values. The presence of an output schema excuses it from explaining return values, but the input-side gaps remain severe given the schema complexity.

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

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

Schema description coverage is 0% across all four parameters, and the step object is a five-variant oneOf with no field descriptions at all. The description's hint that step is a 'structured step' gestures at its object nature but supplies none of the variant-specific meaning (method/url for http_request, code for compute, promptTemplate for llm_provider, etc.), so it fails to compensate for the coverage gap.

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

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

States a clear verb (Create) and resource (step) scoped to an API draft endpoint, so the general action is legible. However, 'supported structured step' is vague about the five concrete step types (http_request, static_json, compute, llm_provider, transform) that the schema's oneOf enumerates, and it gives no differentiation from siblings step_update, step_reorder, or step_delete.

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

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

Provides no when-to-use guidance, no when-not-to-use, and no alternatives. The phrase 'in an API draft endpoint' faintly implies a prerequisite (a draft endpoint must exist), but there is no explicit prerequisite or routing toward step_update/step_reorder for modifying existing steps.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: it does not state that the deletion is permanent, whether the endpoint/draft must be in a particular state, or what happens to step ordering after removal.

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

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

A single, front-loaded sentence with no filler or redundancy. It is efficient, though the brevity comes partly at the cost of the missing details noted in other dimensions.

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

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

An output schema exists, so return values need no explanation, but for a destructive three-identifier mutation the definition is incomplete: no parameter semantics, no preconditions, and no usage routing. The structured fields alone do not cover 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?

All three required parameters (apiId, stepId, endpointId) have 0% schema description coverage and are not mentioned at all in the description. For a tool whose identifiers span three hierarchy levels, the description does nothing to clarify which IDs are needed or how they relate.

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 (delete), a specific resource (structured step), and its container (API draft endpoint), which cleanly separates it from step_create, step_update, and step_reorder. It does not explicitly name a sibling, but the verb alone is unambiguous here.

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 delete versus reorder or update a step, no prerequisites (e.g. draft state, endpoint must exist), and no warning that this is the irreversible option among the step_* family. The agent must infer usage entirely 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 readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the mutation profile is covered. The description adds real value with 'all steps', implying a full-set replacement rather than a partial move, but it never says what happens to steps omitted from stepIds or whether the operation is reversible.

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

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

A single front-loaded sentence with no filler; the ordering semantics land immediately. It is efficient, though the brevity is partly what leaves the usage and parameter gaps.

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

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

An output schema exists, so return values need no explanation. However, for a destructive mutation with 0% parameter coverage, the description should state that stepIds must enumerate every step and what an omitted step implies; that critical detail is only hinted at.

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

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

Schema description coverage is 0% for all three parameters. The phrase 'all steps' usefully clarifies that stepIds must be the complete ordered list, but apiId and endpointId are never mentioned and their relationship (endpoint nested under API) is left unexplained.

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 ('Set the order') and resource ('steps in an API draft endpoint'), which is enough to separate it from step_create, step_update and step_delete. It does not explicitly name those siblings, but the ordering verb 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 step_update (which might also affect ordering) or step_create, and no stated prerequisites such as the endpoint needing to exist in a draft. The agent must infer the trigger condition 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=false and destructiveHint=true, so the agent knows this mutates state, and the description's 'Update' verb agrees with them. Beyond that, it adds only the constraint that the target must be a supported structured step and must live in a draft endpoint; it does not say whether unspecified fields are preserved or wiped, which matters greatly for an update of a complex oneOf payload. With annotations covering the safety profile, a 3 is appropriate.

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 tight sentence with no filler, and the verb-plus-resource is front-loaded. It is efficient but borderline under-specified for a tool with a deeply nested schema.

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

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

An output schema exists, so return values need not be explained, but the input side is complex, involves five mutually exclusive step shapes, and has zero description coverage. Nothing tells the agent how an update interacts with existing step fields or which types are 'supported', leaving a significant gap.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it mentions none of the four required parameters (apiId, endpointId, stepId, step) or the five step-type variants. The one phrase 'structured step' gestures at the step payload but adds no usable semantics; at 0% coverage the description does not compensate.

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 (Update) and resource (a structured step in an API draft endpoint), and the naming/output shape lets an agent distinguish it from step_create, step_delete, and step_reorder. The qualifier 'supported structured' is vague about which step types are updatable, but the core action is unambiguous.

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

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

The description gives no when-to-use context, no prerequisites, and does not point to alternatives such as step_create for new steps or step_delete for removal. Only the phrase 'in an API draft endpoint' hints at the required context, and that is inferred rather than stated.

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