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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, plus has output schema. The description adds value by noting that sensitive fields are masked and that it uses the command bus, and the 'newest first' ordering. It does not contradict annotations; in fact, it reinforces them. Some behavioral aspects like pagination or default limit are covered by schema (default 50) but description adds masking which is beyond schema.

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

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

Two sentences, front-loaded with the main action and scope, then a practical use case. No filler or redundant phrases. Every sentence adds 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?

Given a rich output schema and full parameter coverage, the description is sufficient. It mentions masking (a key behavior) and the diagnostic use case. Missing explicit note about pagination or default limit, but schema covers that. The tool is read-only with annotations, so no need to disclose mutations. Slightly could mention that it doesn't filter by connection type, but not essential.

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

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

Schema description coverage is 100% for both parameters (limit, workspaceId) with good descriptions including defaults and active workspace semantics. The description adds no additional parameter details beyond what the schema provides, so baseline 3 is appropriate. It doesn't need to compensate for gaps.

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 tool lists recent workspace activity events, specifying the event types (workspace, connection, API, database, SSH) and the order (newest first). It distinguishes from siblings like unfour.connection.list or unfour.api.list_history by focusing on 'activity events' across all types via the command bus.

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

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

The description explains when to use it ('useful for diagnosing what changed before a failure started'), implying a diagnostic context. It does not explicitly name alternatives or when-not to use, but the purpose clarity and sibling list implicitly distinguish it. Lacks explicit exclusions but provides clear 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 establish that this is a non-read-only write, so no contradiction is present. The description adds useful behavioral context beyond the annotations: local metadata scope, command-bus execution, environment/production restrictions, and the returned id and summary.

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 concise sentences with no filler. The main action is front-loaded and each sentence adds useful information: what is created, where it is created, environment restrictions, and the return 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?

For a fairly simple two-parameter create tool, the description captures the essential behavior, environment constraints, and return value. It is slightly incomplete on parameter guidance, but that is factored into the parameter semantics score.

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

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

Schema description coverage is 0%, and the description does not explain the name or workspaceId parameters at all. The property names are self-explanatory to some extent, but the description provides no added semantics over the input schema.

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

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

The description has a specific verb and resource: "Creates an API collection in local Unfour metadata." This clearly distinguishes it from sibling tools like update_collection, delete_collection, and list_collections.

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 clear environment-based usage context: dev/test environments allow it, while prod blocks by workspace policy. It does not explicitly name alternatives, but the create operation is obvious enough from the title and sibling set.

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

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

Annotations already signal a non-read-only, non-idempotent write, so the description's added context is valuable: it creates an 'empty' environment in 'local' metadata through the command bus. It does not contradict annotations and adds behavior beyond the structured hints, though it omits error or conflict 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?

Two front-loaded sentences that state the verb and resource immediately. No filler or redundant restatement of the tool name; each clause adds useful information.

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

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

Given a simple two-parameter create tool and an output schema, the description covers the action and policy context. However, the lack of parameter clarification and the absence of any guidance on how this environment relates to other API entities leaves notable gaps, especially with 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain 'name' or 'workspaceId' at all. No meaning is added beyond the raw schema property names, leaving the agent to guess what workspaceId refers to or what naming constraints exist.

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

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

Description uses a specific verb ('creates') with a clear resource ('empty API environment') and scope ('local Unfour metadata'). It distinguishes from sibling tools like update_environment, delete_environment, and list_environments by indicating a create operation with an initial empty state.

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

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

The description gives a clear usage context: dev/test environments allow creation, while prod blocks it by workspace policy. This provides an explicit when-not condition, though it does not name alternative tools such as update_environment for existing environments.

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 are limited to safety flags, but the description adds rich behavioral detail: it 'mutates local Unfour metadata only,' avoids sending traffic, explains production policy differences, and notes the return includes a new request ID and redacted summary. This significantly improves the agent's ability to predict 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 three short sentences, front-loaded with the core operation, and every sentence adds useful behavioral or contextual information. There is no filler or redundant repetition of the tool name.

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

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

The description effectively covers tool behavior, environment constraints, and result shape, and the output schema may fill in return details. However, with 13 input parameters and no input schema descriptions, the record/model for required fields (name, method, url) and optional override (auth, body, headers, collection fields) still remains too vague for a complete understanding.

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%, yet the description gives no input guidance for the 13 parameters. Fields like auth vs authJson, body vs bodyKind, and parentId/collectionId/parentFolderId remain completely unexplained; the description must compensate but does not.

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

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

The description clearly states the tool 'Creates a saved API request record in the workspace' and distinguishes it from a live request by explicitly confirming 'it does not send traffic.' This separates it from sibling tools like send_request and update_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?

The description provides clear context for when the tool is usable ('Dev/test allow it by default') and when not ('prod blocks by workspace policy'). It also gives an implicit when-not by saying it does not send traffic, though it does not name an alternative tool explicitly.

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?

Despite annotations already signaling destructiveness (destructiveHint: true, readOnlyHint: false), the description goes beyond by disclosing what gets destroyed (cascading soft-deletion to folders and requests), distinguishing soft vs hard delete semantics, and revealing environment-dependent auth requirements (confirmation_text needed, prod policy block). This matches the 'what gets destroyed' and 'auth needs' categories for added context.

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

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

Two sentences, zero fluff. The first sentence front-loads the core action and effect, the second delivers the environment/confirmation requirement. Every phrase earns its place, and the density is appropriate for the destructive nature of the operation.

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 operation with 5 parameters, the description efficiently covers the cascade scope, the soft-delete behavior, and environment rules. The presence of an output schema means return values don't need explanation. Minor gaps remain: the confirmationText/confirmation_text distinction isn't fully specified, and the 'content-bound' keyword format is left vague, but the key safety-relevant details are present.

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

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

With 0% schema description coverage, the description carries the full burden for parameter meaning. It mentions 'confirmation_text' and its requirement in dev/test, which directly helps resolve the potentially confusing confirmationText vs confirmation_text distinction. However, it never explains 'confirm', 'workspaceId', or 'collectionId' (though collectionId is self-evident and required). The description partially compensates but leaves the two similar confirmation parameters ambiguous beyond a passing mention.

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-action pair ('Soft-deletes an API collection') with resource scope ('cascades soft-deletion to its folders and requests'). It distinguishes itself from siblings like delete_request (different target resource) by clarifying the cascade behavior, which is unique to this tool among the siblings. The 'through the command bus' detail adds architectural precision.

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 environmental context: 'Dev/test require a content-bound confirmation_text; prod blocks by policy.' This tells the agent when the tool can be used (dev/test with confirmation) versus when it cannot (prod), which is crucial for a destructive tool. However, it doesn't explicitly name alternatives or exclusions versus sibling tools, though the namespace and cascade detail imply when to use it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description goes beyond this by adding that the deletion is a 'soft-delete', that a content-bound confirmation_text is required, and that read-only policies block the action. These are meaningful behavioral details not present in the annotations, though it doesn't discuss reversibility or 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 two sentences long, immediately states the primary action, and includes policy caveats without fluff. Every word adds value, and the structure front-loads the most important 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 destructive operation with 5 parameters, the description covers the core delete behavior and key policy constraints but omits any mention of return values (output schema exists), the purpose of the 'confirm' flag, or what happens to associated resources. It is adequate but leaves notable gaps for an operation of this 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 coverage is 0% and the description only hints at 'confirmation_text' without explaining the relationship between the two similar parameters 'confirmationText' and 'confirmation_text', nor the roles of 'confirm' or 'workspaceId'. The description adds minimal semantic value beyond the schema for parameter understanding.

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 'Soft-deletes an API environment through the command bus,' clearly identifying the verb (delete), resource (API environment), and mechanism (soft-delete, command bus). It distinguishes itself from sibling delete tools by naming the specific resource type and it is not tautological.

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 useful usage context by mentioning the requirement for 'content-bound confirmation_text' and that 'read-only policy blocks deletion.' While it doesn't explicitly name alternative tools or say 'when not to use', the policy conditions offer clear guidance for when deletion is allowed, which is effectively usage direction for a guarded operation.

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 destructiveHint=true and readOnlyHint=false, and the description adds extra behavioral context: 'Guarded policy requires confirmation; read-only policy blocks deletion.' This explains permission-related behavior beyond what annotations provide, though it does not detail what happens to dependent data or partial failures.

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

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

Two sentences with no redundancy. The core action and identifiers are front-loaded, followed by a brief policy note. Every word 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?

While the description is accurate and concise, it leaves several parameters unexplained (confirm, confirmationText, confirmation_text, workspaceId) and does not describe the output or any side effects. Given the tool's complexity and the absence of schema descriptions, more detail is needed for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains environmentId and key, but the schema also has confirm, confirmationText, confirmation_text, and workspaceId with no descriptions. The mention of 'requires confirmation' hints at these fields but does not clarify which one to use or their semantics. This is insufficient for a 6-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?

Description begins with a specific verb 'Deletes', names the exact resource 'API environment variable', and identifies the two key identifiers (environmentId and key). It clearly distinguishes this deletion operation from related sibling tools like delete_environment or delete_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 explicit when-to-use or alternative guidance is provided. The purpose is implied through the verb, but there is no mention of when to choose this over similar operations or any prerequisites. The policy statement hints at conditions but does not directly guide 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?

Even though destructiveHint=true is already in the annotations, the description goes further by explaining that this is only a soft-delete, that confirmation_text is required in dev/test, that prod blocks the action, and that the response will indicate the remaining request count and softDelete=true. This gives the agent important behavioral context beyond the annotation flags.

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 only two sentences and packs in the key environmental constraints, behavioral nuance, and return-value information. There is no filler aside from the brief 'through the Unfour command bus' phrase, which does not meaningfully hurt clarity.

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?

The description explains the operation's outcome and environment-specific guardrails well, and there is an output schema. However, with 5 parameters and no schema-level descriptions, the omission of confirm and workspaceId makes it incomplete for reliable invocation without additional tooling or user clarification.

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 0% schema description coverage, the description had to carry the parameter semantics load, but it only clarifies confirmation_text. It does not explain the role of confirm, workspaceId, or the dual confirmationText/confirmation_text fields, leaving meaningful ambiguity about what values should be supplied.

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 begins with 'Soft-deletes a saved API request,' clearly identifying the action and the resource. It also distinguishes this from hard deletion and ties the behavior to the Unfour command bus, which differentiates the tool from sibling delete tools like delete_collection.

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 clear context on when this tool is usable: dev/test require a confirmation_text, while prod blocks deletion by policy. It does not explicitly mention alternative tools, but for a delete-specific operation the environmental conditions are the key guidance and they are stated clearly.

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, and the description adds meaningful behavioral disclosure: sensitive headers, query parameters, and body fields are masked. This is useful context beyond the structured annotations because it sets expectations about data redaction before invocation.

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

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

The description is two sentences with the core action stated first and a single important behavioral caveat second. Every sentence earns its place; there is no redundancy or 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-only lookup tool with complete parameter descriptions, full annotations, and an output schema, the description covers all necessary context: what is returned, that it is a single entry, and that sensitive fields are masked. No additional behavior or return-format explanation is 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 both historyId and workspaceId are already documented in the input schema. The description adds no parameter-specific detail beyond indicating the tool handles a single history entry, which maps to historyId but does not meaningfully extend the schema's descriptions.

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

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

The description uses a specific verb ('Returns') and identifies the resource ('a single API history entry') with clear scope ('request and response detail'). It also implicitly distinguishes itself from the sibling list_history tool by emphasizing the singular entry and detailed view.

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 usage context is implied through 'single API history entry' and 'detail,' which suggests this tool fits when a specific history entry's full details are needed. However, it does not explicitly name alternatives such as list_history or state when not to use this tool, so guidance remains inferred rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by disclosing that sensitive data is redacted, which is a behavioral trait not covered by annotations. It also mentions the command bus, but that's minor. No 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 description is a single sentence that is concise and front-loaded with the main purpose. No wasted words, and it includes the key detail about redaction.

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 tool has an output schema and annotations, the description is fairly complete. It covers the main purpose and the redaction behavior. It could mention the includeBody parameter's effect, but the schema already describes that. Overall, it's sufficient for a read-only retrieval tool.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns a saved API request with redaction of sensitive fields, which is specific and distinguishes it from sibling tools like list_requests or send_request. However, it doesn't explicitly mention the 'get' action or the resource type beyond 'API request', but the title and name make that clear.

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

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

The description implies usage for retrieving a saved request, but it doesn't explicitly state when to use this vs alternatives like list_requests or get_history. It doesn't mention any prerequisites or exclusions, so it's adequate but not explicit.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile. The description adds the active-workspace scoping and command-bus context, but offers no additional behavioral details such as ordering, pagination, or workspace membership 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?

The description is one focused sentence, front-loads the verb and resource, and contains no filler or redundant detail. It is appropriately sized for such a simple list operation.

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 low complexity, full schema coverage, safe-reader annotations, and presence of an output schema, the description provides enough context for an agent to select and invoke the tool effectively. No major missing information stands out.

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% because workspaceId has an embedded explanation and is optional. The description adds little beyond what the schema already says, relying on the schema to carry parameter meaning.

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 ('Lists') and identifies the resource ('API request collections') plus its scope ('for the active workspace'). This distinguishes it clearly from sibling tools like list_requests or workspace.list.

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

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

The active-workspace scoping implies when the tool is useful, and the workspaceId parameter is covered in the schema. However, it does not provide explicit guidance about when to choose this over related tools such as api.list_requests or when not to use it.

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

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

The description discloses the masking behavior for sensitive variable values and confirms non-sensitive values like base URLs are shown, which is critical context beyond the annotations. This complements the readOnlyHint:true and destructiveHint:false annotations by explaining the safe, read-only nature of the tool and its variable-inspection 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?

Two sentences, zero fluff. The first sentence establishes purpose and scope while acknowledging the umbrella architecture, and the second adds critical security/behavioral context in a compact way. Every word 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 read-only tool with 1 optional parameter and strong annotations, the description covers the essentials: what it does, what it returns (including masking behavior), and scope. It doesn't need to over-explain return structure since output schema exists, and the brief did not require listing sibling alternatives explicitly.

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% (single optional workspaceId), and the description adds behavioral nuance by clarifying the parameter controls workspace selection — though it doesn't explicitly call out the fallback behavior like 'active workspace' — which is a minor gap. The description explains the parameter's masking behavior via the tool's response semantics, adding value beyond the schema.

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

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

The description uses a specific verb ('Lists') with a clear resource ('API environments and their variables') and scope ('active workspace'). It implicitly distinguishes itself from sibling tools like unfour.workspace.list_variables (workspace variables) and unfour.api.list_collections (collections), though it does not explicitly name 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?

The description clearly implies read-only usage by stating it 'lists' environments and variables, and explains the masking behavior without explicitly stating when not to use it or naming alternatives like list_variables. The context of 'requests using variables can be understood' gives clear signals for API request/realm use cases, only stopping short of explicit 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable context: it mentions that sensitive URL parameters are masked, which is a behavioral trait not covered by annotations. It also notes the scope ('active workspace') and the command bus mechanism, which adds transparency.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a practical use case. Every sentence earns its place: the first states what it does, the second adds a security-relevant detail and a usage hint. No fluff.

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 tool's simplicity (2 optional params, no nested objects, output schema exists), the description is fairly complete. It covers purpose, scope, security masking, and a use case. It could mention pagination or the output format, but the output schema likely covers that. The description is adequate for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so both parameters (limit and workspaceId) are already well-documented in the schema. The description adds minimal extra meaning: it mentions 'active workspace' which aligns with workspaceId, and 'recent' which implies a default limit. But it doesn't add syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists recent API request/response history for the active workspace, with a specific verb ('lists') and resource ('API request/response history'). It distinguishes from siblings like unfour.api.get_history (which likely retrieves a single history entry) and unfour.ssh.list_history (which is for SSH, not API).

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 a clear use case: 'Useful for diagnosing when a request started failing.' It implies when to use (when debugging API request failures) but does not explicitly mention when not to use or alternatives. However, the sibling context and the tool's name make it clear this is for API history, not SSH history.

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 clear. The description adds value by noting that sensitive URL parameters are redacted, which is a behavioral trait not covered by annotations. It also mentions the 'command bus' mechanism, adding context. No contradiction with annotations.

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

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

The description is two sentences with zero waste. It front-loads the core purpose and adds one key behavioral note (redaction). Every word 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 the tool's simplicity (2 optional params, no required fields, output schema present), the description is complete enough. It covers purpose, scope, and a key behavioral detail. The output schema handles return value documentation. The only minor gap is not explicitly stating the default behavior of workspaceId, but the schema already covers that.

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

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

Schema description coverage is 100%, so both parameters (workspaceId and collectionId) are already documented in the schema. The description adds minimal extra meaning beyond the schema, only implying that workspaceId defaults to the active workspace. This meets the baseline of 3 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 clearly states the tool lists saved API requests for the active workspace, with a specific verb ('lists') and resource ('saved API requests'). It distinguishes from siblings like unfour.api.get_request (single request) and unfour.api.list_collections (collections) by focusing on requests and mentioning the command bus context.

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

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

The description implies usage for listing requests in the active workspace, with optional filters for workspace and collection. It doesn't explicitly state when not to use it or name alternatives, but the context of 'active workspace' and optional filters provides clear usage context. Sibling tools like unfour.api.get_request suggest alternatives for single-request retrieval, but this isn't stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds substantial behavioral context: environment-dependent method restrictions, non-2xx response behavior, masking of sensitive headers/cookies/URL tokens/JSON body fields, and the distinction between HTTP timeout and the MCP safety deadline. This goes well beyond what annotations provide.

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 compact and front-loaded: the core action and two modes appear in the first sentence, followed by the use case, environment restrictions, response behavior, and masking. Every sentence adds information; there is no filler or repetition of schema 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 tool with 11 parameters, no required parameters, and an output schema, the description covers the essential decision points: which mode to use, environment restrictions, response handling, and security masking. The output schema handles return values, so the description doesn't need to. The only minor gap is that it doesn't explicitly say what happens if both requestId and method/url are provided, but the schema's 'Omit when sending method/url directly' covers that.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters. The description adds value by explaining the two mutually exclusive modes (requestId vs method/url), the environment-dependent method restrictions, and the timeout semantics (0 disables HTTP timeout, 120s MCP deadline). It doesn't detail every parameter, but the schema already does that, and the description clarifies the key relationships.

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 ('sends') and resource ('API request through the Unfour command bus'), and distinguishes two modes: replaying a saved request by requestId or sending an ad-hoc request by method/url/headers/query/body. It also names a concrete use case ('reproduce API failures during agent troubleshooting'), which clearly separates it from sibling tools like list_requests or get_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?

The description explicitly explains when to use the tool ('reproduce API failures during agent troubleshooting') and gives environment-specific guidance: dev allows all methods, test marks mutating methods as write risk, prod only allows GET/HEAD/OPTIONS. It also clarifies that non-2xx responses return structured data rather than MCP tool failure, which tells the agent how to interpret results. This is strong 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 indicate readOnlyHint=false (not read-only) and idempotentHint=false. The description adds meaningful behavioral details beyond these: 'Empty values are allowed,' 'Omitted isSecret/description preserve existing metadata,' and 'returned secrets are masked.' These are not derivable from the schema or annotations and help the agent understand edge-case 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?

Three concise sentences, front-loaded with the core action. Each sentence adds distinct value: the action, the empty-value edge case, and the preservation/masking behavior. No fluff or repetition.

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

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

For a 7-parameter tool with an output schema, the description covers the most critical contextual aspects: create-or-update behavior, empty values, metadata preservation, and secret masking. Missing details like the role of 'enabled' and 'workspaceId' are minor, and the presence of an output schema reduces the need to describe return values. Overall, sufficient for an agent to call the tool correctly in most scenarios.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly names environmentId and key as locators, implies value via 'Empty values are allowed,' and explains behavior for isSecret/description when omitted. However, it does not address the 'enabled' or 'workspaceId' parameters, leaving some parameter semantics undocumented. It partially compensates but is not exhaustive.

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

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

The description opens with a specific verb phrase, 'Creates or updates,' and names the exact resource, 'one API environment variable,' with the identifying keys (environmentId and key). This clearly distinguishes the tool from siblings like workspace.create_variable or api.update_environment, and the title reinforces the 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?

The description implies usage by stating what the tool does, but it does not explicitly state when to use this tool versus alternatives such as workspace.create_variable or api.update_environment. There is no mention of exclusions or conditions that would route an agent to a different tool. The naming and context make the use case inferable, but the description itself offers no explicit 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?

Beyond the annotations (not read-only, not idempotent, not destructive), the description adds that the update goes through a command bus and has environment restrictions. However, it does not elaborate on side effects, reversibility, or permission requirements, providing only moderate additional transparency.

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 concise (two sentences) and well-structured, conveying the essential information without unnecessary detail or repetition.

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

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

For a simple rename operation, the description covers the action, the fact it modifies local metadata, and environment constraints. Since an output schema is present, return value details are not needed. It could mention that only the name field is updated, but that is implied by 'renames'. Overall, it is sufficiently complete for the 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?

The description implies that 'name' is the new collection name and 'collectionId' identifies the target collection, but it does not explicitly define each parameter. The workspaceId is mentioned only in the context of environment blocking, giving some insight but not a full explanation. The schema lacks descriptions, so the tool description partially compensates but could be more explicit.

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 that the tool renames an API collection, which is a specific and unambiguous action. It also mentions the local metadata aspect and command bus, making the purpose distinct and easy to understand.

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 usage context by noting that the operation is allowed in dev/test environments but blocked in production, and it operates on a specific workspace. This helps users decide when to invoke it, though it does not explicitly compare with alternative tools like update_request or create_collection.

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

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

The description adds genuinely useful behavioral context beyond the annotations (readOnlyHint: false, destructiveHint: false) by disclosing that sensitive variable values are masked in the result and that production is blocked by workspace policy. These additions help an agent reason about mutation side effects and output handling. No contradiction with annotations — 'Updates' is consistent with readOnlyHint: 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?

Three short, purposeful sentences: purpose, security/masking behavior, and policy constraint. Zero wasted words; each sentence earns its place and 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?

Given there is an output schema (reducing the need to document return values) and given the tool's moderate complexity, the description covers the most important operational nuances (masking, prod block). However, it leaves the key update-semantics question unanswered — whether passing a partial variables array replaces or merges existing variables — which is critical for a mutation tool like this. The 'through the command bus' detail adds minimal value.

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 at 0%, the description must compensate, and it partially does by naming 'name and variables' and adding the masking nuance relevant to variable values. However, it doesn't clarify the semantics of the `enabled` field on each variable, how `workspaceId` resolves, or whether the variables array is a full replace or a merge — a critical distinction for an update 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?

'Updates an API environment name and variables' uses a specific verb, specific resource, and names the exact fields being modified. It clearly differentiates from sibling tools like create_environment, delete_environment, and list_environments by stating the scope of the update. The naming of specific fields (name, variables) removes ambiguity about what the update covers.

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?

'Dev/test allow it; prod blocks by workspace policy' provides explicit context on which environments support this operation, preventing wasted calls in production. However, it doesn't explicitly name alternatives or say 'use create_environment to create, this to update' — the sibling contrast is implicit rather than stated.

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

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

The description adds significant behavioral context beyond the annotations: it states the update is partial (omitted fields keep values), confined to local metadata, subject to environment policies, and that the return is a redacted summary. These details are not present in annotations and help set expectations around side effects and limitations. No contradictions with annotations.

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

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

The description is two concise sentences that front-load the core action and immediately follow with key behavioral notes. Every sentence delivers new information without fluff, making it highly 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?

The tool is moderately complex (14 params) and lacks schema-level descriptions, so the description carries a heavy burden. It provides some completeness through partial-update semantics and return format, but misses field-level clarifications and any mention of error conditions or required authentication. Given the output schema exists, it partially compensates, but the description still leaves 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?

With 0% schema description coverage, the description must explain parameter meanings, but it only offers the generic behavior that omitted fields retain prior values. It does not describe what each of the 14 parameters (url, auth, body, method, etc.) represents or how they interplay. This is inadequate for an agent to correctly use the tool, leaving significant ambiguity.

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 ('Updates a saved API request record') and names the resource type (API request) via the command bus. It distinguishes itself from sibling tools like create_request and delete_request by using 'update' and referencing existing records. The mention of partial updates via omitted fields further clarifies its 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?

The description provides context for when to use the tool by noting it updates saved requests and explicitly states environment constraints ('dev/test allow it, prod blocks or requires future explicit policy'). However, it does not explicitly compare with alternatives like create_request or delete_request, nor does it state when to avoid using it, such as for new records.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context with 'safe summaries' and 'active workspace', giving agent signals about output scope and safety beyond the structured annotations.

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

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

The description is one short, focused sentence. It front-loads the core action and adds scope and result-nature information without unnecessary words or redundancy.

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

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

For a simple tool with one optional parameter, a strong annotation profile, and an output schema, the description is reasonably complete. It could be more explicit about which connection types are covered and how this tool relates to db/ssh-specific connection listings, 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?

The single parameter is fully described in the input schema with an enum, default value, and clear description. Since schema description coverage is 100%, the description does not need to repeat parameter details; 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 description clearly identifies an action and scope: listing connection summaries scoped to the active workspace. It uses a concrete verb and noun phrasing, but it does not explicitly distinguish this generic connection listing from sibling tools such as unfour.db.list_connections or unfour.ssh.list_connections.

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 about when to use this tool versus alternatives such as db.list_connections or ssh.list_connections. It also does not mention whether the optional type filter changes which sibling tool would be 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?

Beyond the annotations, the description discloses important side effects: password storage in the OS credential store, persistence of only a reference, and never returning the credential. This adds valuable transparency not covered by the annotations.

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

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

The description is concise, consisting of two clear sentences. It efficiently conveys the core action and important security details without unnecessary verbosity.

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 large set of sibling tools, the description lacks sufficient context for when to use this specific tool. It does not mention any prerequisites, edge cases, or the expected outcome/return, and it does not clarify the role of many parameters. This leaves the agent with incomplete information for decision-making.

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 lists 13 parameters with no descriptions, and the description only mentions 'optional password input'. It fails to explain the meaning or purpose of host, port, sslMode, database, username, sqlitePath, workspaceId, credentialRef, or credentialLabel, leaving the agent without essential context for correct usage.

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 tool's purpose: creating a saved database connection. It also distinguishes it from sibling tools like listing or testing connections, leaving no ambiguity about its function.

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 tool is used when creating a new connection, but it does not explicitly mention when to prefer this over alternatives such as test_connection or list_connections. The guidance is implied rather than explicit.

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

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

Annotations already mark this as destructive and non-read-only, but the description adds important behavior beyond them: the deletion is a soft delete, it goes through CommandBus, and a guarded confirmation policy applies. This meaningfully clarifies what the tool actually does.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the policy constraint is stated efficiently in the second 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?

An output schema exists, so return-value details are not required, and annotations cover the destructive safety profile. However, for a policy-guarded delete, the agent still needs to know how to satisfy the confirmation requirement; the description mentions confirmation but does not map it to confirm/confirmation_text, and 'revision' is referenced without a corresponding parameter.

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

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

Schema description coverage is 0%, so the description must compensate for the parameters, but it does not explain confirm vs confirmation_text or state that connectionId is required. It hints at workspace and connection binding, but the two confirmation-related parameters remain ambiguous.

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 (soft-delete) on a specific resource (a saved connection) and is consistent with the title 'Delete Database Connection.' The verb and resource make it distinct from sibling operations like update_connection or create_connection.

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 clear policy context: confirmation is required, it must be bound to workspace/connection/revision, and read-only policy rejects deletion. This tells the agent when deletion will be permitted, though it does not explicitly name alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful boundary that it is metadata-only, but 'with runtime metadata capabilities, through the Unfour command bus' is vague rather than informative, and no auth or latency behavior is disclosed.

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

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

Two compact sentences with the scope and the exclusion front-loaded, which is efficient. The phrase 'with runtime metadata capabilities, through the Unfour command bus' is filler that does not carry actionable meaning and slightly dilutes the otherwise tight structure.

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, a fully documented parameter schema, and read-only annotations, the description needn't explain return values or safety. It states the resource and the metadata-vs-data boundary, which is sufficient for correct invocation, though it stops short of describing any return-shape nuance.

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

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

Schema description coverage is 100%, so all five parameters (including optional schema, catalog, and workspaceId) are already documented in the schema. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource ('Describes a table') and enumerates the returned artifacts (columns, indexes, foreign keys, DDL), which lets an agent distinguish it from siblings like db.list_tables, db.query_readonly, and db.export_table. The closing clause 'Does not read table data' draws an explicit boundary against the data-reading siblings.

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

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

The negative constraint 'Does not read table data' functions as an implicit when-not, steering the agent away from this tool for data retrieval. However, no alternative is named and there is no positive statement of when to prefer this over db.list_tables or db.query_readonly, so usage is only implied.

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

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

The description provides extensive behavioral context beyond the annotations: environment-specific write permissions (dev default, test confirmation, prod blocked), a mandatory second-call confirmation flow for dangerous SQL, and details on return values (affectedRows, statementType, durationMs, engine safety metadata). This significantly enriches the minimal annotation set and is critical for safe, correct usage.

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?

Approximately 90 words across five sentences, each adding distinct value: purpose, usage scenario, environment rules, confirmation flow, and return payload. It is information-dense but efficient, with the core purpose 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 high-complexity mutation tool with no schema descriptions, the description covers the essential operational aspects: what it does, when to use it, safety guardrails, and the confirmation protocol. It could expand on high-risk SQL specifics or `dryRun`/`transaction` behavior, but given it has an output schema and the description handles the most critical safety aspects, it is largely 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?

With 0% schema description coverage, the description carries full responsibility for clarifying parameters. It clarifies the `confirmation_text`/`confirmationText` flow and implies `connectionId` and `sql`. However, it leaves the other nine parameters (dryRun, transaction, schema, catalog, etc.) unexplained, which is a significant gap given the total absence of schema descriptions.

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

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

The description uses a specific verb ('Executes'), a clear resource ('one SQL statement against a saved database connection'), and a mode ('through the Unfour command bus'). It clearly differentiates from siblings like `unfour.db.query_readonly` and `unfour.db.explain` by specifying it's for INSERT/UPDATE/DELETE/DDL and data repair.

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

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

It explicitly states when to use the tool: 'Use for INSERT/UPDATE/DELETE/DDL when an agent needs to repair dev/test data.' It also sets expectations about behavior in dev/test/prod environments, which informs when the tool is applicable. However, it does not explicitly name the read-only alternatives like `unfour.db.query_readonly`.

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

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

The description states it is read-only in dev/test/prod and returns structured columns/rows, durationMs, and truncation metadata, which adds valuable behavioral context beyond the annotations. There is no contradiction with the annotations (readOnlyHint, idempotentHint, destructiveHint all align). The description also implies non-destructiveness and clarifies expected outputs, though it could mention that it does not execute the query for side effects or that it requires an existing connection.

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 concise, at two sentences, and front-loads the action and use case. Every phrase adds value: the command bus, read-only guarantee, use-before-optimization guidance, and return value highlights. No filler or repetition of schema details.

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 tool's moderate complexity (7 params, but only 2 required) and the presence of an output schema (which explains return values), the description provides sufficient context for selection and core usage. It covers the purpose, use case, safety profile, and return format highlights. The main gap is the lack of parameter semantics, but the required parameters (connectionId, sql) are intuitive from the description, and the output schema handles return structure.

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

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

Schema description coverage is 0%, so the description must compensate for the seven parameters. It mentions 'saved database connection' and 'read query', but does not explain parameters like limit, schema, catalog, timeoutMs, workspaceId, or connectionId. The description adds minimal semantic detail beyond the schema; it indicates connectionId and sql are key but does not explain their roles or optionality, so the agent may struggle with how to set these parameters for optimal use.

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 tool runs EXPLAIN for a read query against a saved database connection, which is a specific verb+resource combination. It distinguishes itself from siblings like unfour.db.query_readonly and unfour.db.execute by focusing on query optimization via EXPLAIN, making its purpose 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 explicitly says to use it 'before optimizing slow SELECT/WITH queries', giving a clear use case. However, it does not explicitly mention when NOT to use it or name alternative tools for other scenarios, such as unfour.db.query_readonly for actual data retrieval, though the context implies it.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world). The description adds real value beyond them: it discloses the managed-directory write target, that no destination path is accepted, the content-bound confirmation requirement for unbounded data exports, and that file metadata is returned.

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

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

Four tight sentences with zero redundancy; the scope and target directory are front-loaded, and the confirmation and return-value notes each carry distinct 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?

An output schema exists, so return values need no elaboration, and the description covers the key confirmation behavior. But for a 13-parameter tool at 23% schema coverage it omits meaningful parameter semantics, and the duplicate confirmation parameters (confirm/confirmationText/confirmation_text) are left unclarified.

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 23% across 13 parameters, so the description is expected to compensate, and it covers columns, filters, limit, and content. It leaves format, catalog, schema, workspaceId, and the three confirmation-related parameters (confirm, confirmationText, confirmation_text) unexplained, so compensation is partial.

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 (exports), a specific resource (one table), and a specific destination (Unfour's managed exports directory), plus the constraint that no destination path is accepted. This is unambiguous and easily separable from siblings like db.query_readonly or db.execute.

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?

Implies when the confirmation flow kicks in ('Data exports without limit require content-bound confirmation; omitted limit still means all matching rows'), which is useful operational context. However, it never states when to choose this over db.query_readonly or db.execute, nor any prerequisites, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it returns 'safe summaries without passwords, tokens, or connection strings', which is important behavioral information beyond the annotations. No 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?

Two sentences, zero waste. The first sentence states the purpose and scope, the second adds a critical safety detail. Perfectly front-loaded and 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?

The tool is simple (1 optional param, no required params, output schema exists). The description covers the purpose, scope, and a key safety behavior. It doesn't describe the output format, but the output schema exists, so that's not required. Complete enough for a list 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?

Schema description coverage is 100% for the single optional parameter (workspaceId), so the schema already documents it. The description adds the context that it uses the active workspace if omitted, which is helpful but not extensive. 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 description clearly states the tool lists saved database connections for the active workspace, using a specific verb ('Lists') and resource ('saved database connections'). It distinguishes from siblings like unfour.connection.list and unfour.ssh.list_connections by specifying 'database' and 'active workspace'.

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

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

The description implies usage context: it's for listing database connections in the active workspace, and the optional workspaceId parameter allows targeting a different workspace. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough given the sibling 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=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral details: default/max limit, masking of SQL literals, withholding of statements with comments or sensitive markers, and promise to return execution summaries rather than raw errors or rows. This goes beyond what annotations provide, enhancing the agent's understanding of data shape and privacy.

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

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

Three sentences, each adding essential detail: the purpose, the key limits and masking behavior, and the nature of returned data. No fluff; the most critical info (workspace scoping, limits) is front-loaded, and the privacy constraints follow logically.

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

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

For a list operation with a clear output schema (execution summaries) and minimal parameters, the description fully covers what an agent needs: the scope, the limits, what is excluded, and what is returned. There is no ambiguity about the function's behavior or output format.

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%, but there are only two parameters. The description mentions 'default 50, maximum 200' which directly clarifies the 'limit' parameter, and implies workspace scoping for the workspaceId. However, it does not explicitly define field types or requirements, but given the simplicity, the baseline 3 is justified.

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 tool lists workspace-scoped query history, distinguishing it from similar tools by naming workspace scoping, default/max limits, and filtering behavior. Identifies the resource (database query history) with a specific verb (list).

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

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

The description clearly states when to use this tool (to list query history) but does not explicitly contrast with alternatives like unfour.api.list_history or unfour.ssh.list_history. However, the workspace scoping and explicit masking behavior imply usage 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: the operation runs through the 'Unfour command bus' and is restricted to saved connections, which is a real operational constraint. It adds little else (no pagination/return behavior), but that is largely carried by the output schema.

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

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

Three short sentences, front-loaded with the core action, then scoping parameters, then the connection constraint. No filler or restatement of the title.

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

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

With an output schema, rich annotations and fully documented parameters, the description only needs to establish scope and prerequisites, which it does. The one remaining gap is that it does not hint at result ordering or the effect of the limit parameter, but that is minor given the schema coverage.

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

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

Schema description coverage is 100%, so the schema already documents limit, schema, catalog, workspaceId and connectionId in detail. The description only restates that catalog and schema scope the listing and that connectionId is required, adding no syntax or format information beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Lists) and resource (tables and views) scoped to a saved database connection, which clearly separates it from siblings like unfour.db.describe_table and unfour.db.query_readonly. It does not explicitly name a sibling, but the resource scope makes the intent unmistakable.

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

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

Gives a clear precondition (requires a saved connectionId) and an explicit exclusion (does not accept ad-hoc connection strings), which tells the agent when this tool applies versus constructing a new connection. It stops short of naming an alternative tool for the ad-hoc case, so it is strong but not exhaustive.

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 the specific allowed statement types and the rejection of write/DDL/multi-statement queries, which is useful behavioral context beyond the annotations. It doesn't mention return format, but the output schema exists, so that's 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?

Three sentences with no waste. The core purpose and constraints are front-loaded, and the sibling reference is concise. 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?

Complete for a read-only query tool. The description covers allowed statements, rejected operations, and parameter alignment with siblings. The output schema exists, so return values are documented. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds the note that optional catalog, schema, and timeoutMs match unfour.db.execute and unfour.db.explain, which is a small addition. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Executes'), a resource ('read-only SQL query against a saved database connection'), and the allowed statement types. It clearly distinguishes this from unfour.db.execute and unfour.db.explain by naming them as siblings and noting the matching optional parameters.

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 explicitly lists which SQL statements are allowed and which are rejected, and it references sibling tools (unfour.db.execute and unfour.db.explain) for the optional parameters. This gives clear guidance on when to use this tool versus alternatives.

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

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

The description mentions the return value (success and server version), which is informative. Combined with annotations (readOnly, idempotent, non-destructive), it gives a clear picture of the tool's behavior, though it doesn't explicitly state the lack of side effects beyond 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?

The description is a single sentence that is concise and directly states the action and expected output. No unnecessary details or fluff.

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 test tool, the description sufficiently covers what the tool does and what it returns. It does not require extensive elaboration, and the provided information is complete in context.

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 description does not add any details about the parameters beyond what the input schema already provides. Since the schema has clear descriptions for both workspaceId and connectionId, the description adds no extra meaning, aligning with the baseline 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 clearly states the tool's function: testing connectivity to a saved database connection. The action is specific and unambiguous, and the tool name reinforces the 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?

The description does not explicitly contrast this tool with related alternatives (e.g., create_connection, list_connections). While the name implies its role, there is no guidance on when to prefer it over other connection-related tools.

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

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

With all annotations false, the description carries the behavioral burden and delivers: partial-update semantics ('Omitted fields and stored credentials are preserved'), a clear limitation ('Secret rotation is not exposed'), a precondition ('The ID must exist in the selected workspace'), and response scope. These go well beyond what the annotations express, giving the agent accurate expectations about side effects and return content.

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

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

Four sentences, each earning its place: purpose first, then precondition, partial-update behavior, and the secret-rotation caveat with response shape. The only minor blemish is 'through CommandBus,' which adds implementation detail without helping an agent decide or invoke correctly.

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

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

For an 11-parameter, 1-required mutation tool with zero parameter descriptions, the description covers the essentials: what is updated, the workspace precondition, merge semantics, the secrets limitation, and result scope. The presence of an output schema and self-documenting enums offsets the missing per-parameter prose. Only permission requirements and error behavior for a nonexistent connectionId are 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?

Schema description coverage is 0%, so the description must compensate. It clarifies high-level semantics—connectionId must reference an existing item, omitted fields are preserved (explaining why all 11 params are optional), and no secret parameter exists. However, it does not explain individual parameters beyond what names/types/enums already convey, leaving host/port/driver/sslMode/database/readOnly/sqlitePath semantics to inference.

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

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

The description opens with a specific verb-plus-resource: 'Updates saved connection metadata through CommandBus.' Among siblings like create_connection, delete_connection, list_connections, and test_connection, the term 'saved connection metadata' clearly marks this as the modifier of existing connection configs and distinguishes it from query/execution tools. No ambiguity about what action is performed.

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 context is implied rather than stated: 'Updates saved connection metadata' and 'The ID must exist in the selected workspace' suggest the agent reaches for this when editing an existing connection. However, there are no explicit when-not-to-use rules, alternatives (e.g., ssh.update_connection for SSH connections, test_connection for connectivity), or exclusion conditions naming sibling 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful semantics beyond them: it is a *request* (may not be immediate) and 'remote effects are not rolled back', which is important consequence information an agent cannot infer from the annotations.

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

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

A single front-loaded sentence with zero filler that still conveys the key action and the most important consequence. Every clause earns its place.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, with 0% parameter coverage and no statement of prerequisites (run must be in 'running' status) or how cancellation is observed, the definition is only minimally adequate for a mutation-style 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?

Schema description coverage is 0% with two parameters (required runId, optional workspaceId), so the description carries the burden. It only obliquely references 'a running Flow'; it never explains what runId identifies, that workspaceId scopes the lookup, or their formats. The gap is not compensated.

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 ('Request cancellation of a running Flow'), which is clearly distinct from siblings like unfour.flow.run, unfour.flow.get_run, and unfour.flow.list_runs. It does not explicitly name those siblings, but the 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 phrase 'of a running Flow' implies the trigger condition (the run must be active) but the description never states when to reach for this tool versus the alternatives, nor any exclusion such as not calling it on an already-finished run. Usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation/safety profile is covered. The description adds genuinely non-obvious behavior: run history is preserved across the delete, and guarded workspaces demand a revision-bound confirmation. It stops short of stating auth requirements or whether concurrent runs are affected.

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

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

Two short sentences, front-loaded with the destructive action and its scope, then the confirmation prerequisite. No filler and nothing 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?

An output schema exists so return values needn't be described, and the destructive annotation is supplemented by the retention and confirmation notes. Still, for a 5-parameter mutation with zero schema description coverage, the description omits enough parameter-level detail to leave an agent guessing at 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?

Five parameters at 0% schema description coverage, so the description carries the full burden. It gestures at the confirmation concept but never maps it to the actual fields (confirm, confirmationText, confirmation_text) or explains flowId/workspaceId formats, leaving duplicate confirmation parameters 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 (Delete) and resource (a saved Flow definition), and adds a meaningful scope qualifier — run history is retained. This cleanly distinguishes it from siblings like unfour.flow.save, unfour.flow.get, and unfour.flow.run.

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

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

The description implies usage by noting that guarded workspaces require confirmation bound to the current revision, which is a useful precondition. However, it gives no explicit when-to-use vs when-not guidance and does not mention what happens to running flows or how to recover from a mistaken 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only a target-consumer note ('for use in Desktop Canvas or MCP') and says nothing about auth requirements, errors for missing flows, or workspace scoping behavior. It clears the lower bar set by annotations but adds little.

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 the action front-loaded and zero filler. It is appropriately sized, though that brevity is also what leaves the parameter and usage gaps unaddressed.

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 rich output schema exists (the full Flow definition structure), so return values need not be explained. But for a retrieval tool with two undocumented parameters and no guidance on when to prefer it over flow.list or flow.get_run, the description is only minimally 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%, so the description carries the burden of explaining the two parameters, yet it mentions neither flowId nor workspaceId. The schema supplies types and patterns but no meaning, and the description does nothing to clarify required vs optional or what workspaceId scoping implies.

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

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

States a specific verb (Read) and resource (saved Flow definition), which cleanly distinguishes it from unfour.flow.get_run. However, it does not name or contrast with sibling tools like flow.list or flow.get_run, leaving the agent to infer the distinction. Clear purpose but no sibling differentiation.

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

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

The description says what it does but never says when to use it versus alternatives such as unfour.flow.list (enumerate) or unfour.flow.get_run (inspect execution). No conditions, prerequisites, or exclusions are given. Usage must be inferred 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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful context that results are redacted, but does not explain permissions, data scope boundaries, or pagination behavior.

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

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

The definition is a single front-loaded sentence with no wasted words. It is concise, though the brevity contributes to missing parameter and usage guidance.

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

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

An output schema exists, so return values need not be described. However, for a two-parameter retrieval tool with 0% schema description coverage and no usage guidance, the description is too incomplete to help an agent invoke it correctly beyond the basic action.

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

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

Schema description coverage is 0% for two parameters, and the description does not explain runId or workspaceId at all. An agent must infer how to identify the target run and whether workspaceId is required or scoping.

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: reading a Flow run's complete redacted run history. It is clearly distinguishable from list_runs and flow.get, though it does not explicitly name sibling alternatives. The phrase 'shared with Desktop' adds scope but is slightly ambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives like unfour.flow.list_runs or unfour.flow.get. It implies retrieval of a run, but leaves context and exclusions to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds one useful behavioral note — that results are abbreviated summaries and that full definitions require `get` — but says nothing about result size, ordering, pagination, or whether the list is workspace-scoped or global.

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 naming the action, the returned artifact, and the alternative tool. Zero waste and no filler.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description adequately covers purpose plus the summary-vs-definition distinction. It remains incomplete on the two things an agent most needs for correct invocation: workspace scoping of the optional parameter and disambiguation from unfour.flow.list_runs.

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

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

There is one optional parameter (workspaceId) with 0% schema description coverage, and the description never mentions it. The description does not explain whether omitting it lists flows across all workspaces or defaults to the current one — meaningful semantics that are left entirely undocumented in both the schema and the description.

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

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

States a specific verb and resource (list saved Flow summaries) and contrasts with the sibling get tool in the same sentence. However, the term 'Flow summaries' is not disambiguated from the closely named sibling unfour.flow.list_runs, which an agent could easily confuse with this tool given the schema's summary objects carry run-like fields (status, startedAt, finishedAt).

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 one explicit routing rule: use `get` when you need the complete definition rather than a summary. This is clear when-to-use guidance for the list-vs-get choice, but it is silent on when to use this versus unfour.flow.list_runs, and states no exclusions or preconditions (e.g., workspace scoping) for the listing 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 read-only, idempotent, non-destructive behavior. The description adds useful payload context: it returns lightweight FlowRunSummary records and avoids loading full run details. It does not mention pagination behavior.

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

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

The definition is a single front-loaded sentence with no wasted words. It is appropriately concise for the core purpose, even though other dimensions are under-specified.

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. But with four undocumented input parameters and no mention of required flowId, scoping, or pagination, the description is not complete enough to guide invocation beyond the bare 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?

The tool has four parameters and 0% schema description coverage. The description mentions no parameter names, required flowId, workspace scoping, limit, or cursor, so it fails to compensate for the missing schema descriptions.

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

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

The description states a specific verb ("Read"), resource ("FlowRunSummary history"), and scope ("without loading run details"). It implies contrast with detail-loading siblings like unfour.flow.get_run, but does not explicitly name an alternative tool.

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?

"Lightweight ... without loading run details" implies this tool should be used when summary-only history is sufficient. However, it does not explicitly state when to use it versus alternatives or any 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?

Adds meaningful traits beyond the annotations: payload-bound confirmation is required even with full_access, policy can block execution, and cancellation does not undo effects. These are valuable operational facts for a non-destructive but open-world mutating tool.

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

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

Four dense, front-loaded sentences with no wasted filler. Some phrasing ('payload-bound confirmation') is cryptic, but overall it is efficient and scannable.

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 coverage, and behavioral traits are decently covered. But for a tool with 8 parameters, nested objects, and 0% schema description coverage, the absence of parameter guidance leaves the definition 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 0% across 8 parameters (flowId, inputs, confirm, confirmationText, confirmation_text, workspaceId, environmentId, secretInputNames). The description mentions 'payload-bound confirmation' but never maps it to the confirm/confirmationText params nor explains any input semantics, leaving a major 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+resource ('Start a Flow'), which is clearly distinguishable from siblings like unfour.flow.cancel_run and unfour.flow.get_run. It does not explicitly name those alternatives, but the 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?

Implies usage context by noting the confirmation requirement and that read-only/disabled policy blocks execution, giving implicit preconditions. However, it never states when to use this versus alternatives such as unfour.flow.cancel_run or unfour.flow.get_run, nor exclusions for appropriate scenarios.

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 mutation/idempotency profile is covered. The description usefully adds that validation runs and that updates enforce a current-revision check (optimistic concurrency), but it omits what happens on a stale revision or validation failure. Adds context beyond annotations without being rich.

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

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

Two tight sentences with no filler, and the create/update behavior is front-loaded right after the purpose statement. Sized appropriately for a definition whose nested schema is large.

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 the description states the validation and revision invariants. But it leaves workspaceId behavior, error handling on stale revisions, and permission needs unaddressed, which is thin for a mutation tool with a large nested input schema.

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

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

Schema description coverage is 0%, and the description covers only the nested id and revision fields (empty id = create, revision must be current), leaving the top-level workspaceId and the bulk of the definition structure undocumented. The id/revision semantics are genuinely useful beyond the raw schema, but coverage of the actual two parameters is incomplete.

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 (Save) and resource (FlowDefinition) and adds the create-vs-update semantics, which clearly marks it as the write counterpart to flow.get, flow.delete, and flow.run. It does not explicitly name a sibling, but the save semantics distinguish it adequately.

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?

"Empty id creates; updates require the current revision" gives a concrete usage condition and the precondition for the update path, which is more than nothing. However, it never contrasts with alternatives such as flow.run or flow.get, nor states when not to use it, so guidance is implied rather than explicit.

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

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

The description is consistent with annotations (a mutating operation where readOnlyHint=false). It adds 'active' scoping (only running tasks can be canceled) and 'command bus' mechanism, but doesn't disclose what happens if the run has already completed or failed, nor the non-idempotent behavior hinted by idempotentHint=false. No contradiction with 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?

A single, tightly worded sentence that front-loads the verb and object with zero filler. Every word earns its place, and the sentence is appropriately sized for this simple cancellation operation.

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

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

For a 2-parameter cancel operation with an output schema available, the description is minimally adequate. It identifies the action, target, and mechanism, but omits useful context like behavior on already-finished runs. The presence of an output schema mitigates some gaps, though the description could have mentioned cancellation semantics without bloating the 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 carried the full burden for explaining parameters but says nothing at all about them. The parameter names runId and workspaceId are reasonably self-explanatory, which is the only saving grace, but no additional semantic detail is provided for the two-parameter 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 ('Cancels') with a clear object ('active SSH task run') and states the mechanism ('through the command bus'). This clearly differentiates cancellation of a run from sibling operations like clearing runs or reading run logs, though it doesn't explicitly contrast with the similar-sounding clear_task_runs sibling.

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

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

No guidance is provided on when to use this tool versus alternatives. Given siblings like unfour.ssh.clear_task_runs and unfour.ssh.run_task, an agent could easily confuse 'cancel a run' with 'clear runs' — explicit when/when-not guidance would be valuable, but none 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?

The annotations already disclose destructiveHint=true and readOnlyHint=false. The description adds the important detail that both data records and local log files are removed, and that a guarded confirmation policy is mandatory. This goes beyond the raw annotations without contradicting them.

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 concise, front-loaded sentences with no superfluous text. The first sentence establishes the core action and scope, the second sentence gives a critical policy caveat.

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

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

Given the destructive nature and five parameters, the description covers the basic scope and safety requirement but omits the relationship between taskId and workspaceId and the precise confirmation flow. The output schema is provided, so return values are not needed in the description, but enough ambiguity remains to warrant a middling score.

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

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

Schema description coverage is 0%, so the description must compensate, but it provides only high-level hints about the parameters ('one task or the workspace' and 'content-bound confirmation'). The meaning of five parameters, including the duplicate confirmationText/confirmation_text fields and how to satisfy the guard, are left unresolved.

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, 'Deletes', names the destroyed resources ('SSH task run records and local log files'), and defines scope ('for one task or the workspace'). It clearly distinguishes this tool from siblings like cancel_task_run or delete_task, which affect different resources.

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 conveys when to use the tool: when permanently removing saved run history and logs for a task or workspace. The 'Guarded policy requires confirment' clause provides a usage constraint, but it does not explicitly name alternatives or state when not to use it.

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

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

The description adds valuable behavioral context beyond the annotations: optional secret input is stored in the OS credential store, only a credential reference is persisted, and the tool never returns the secret or credential reference. This meaningfully discloses side effects and data handling. It does not mention all possible side effects, but the added detail is strong.

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

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

The description is two sentences, front-loaded with the primary purpose, and contains no filler. Every sentence contributes meaningful information about creation and credential handling.

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 tool has nine parameters, four required fields, and zero schema-level descriptions, the description is not complete enough for reliable invocation. It covers credential storage well but omits guidance on authKind selection, keyPath vs. secret, port defaults, workspaceId usage, and the meaning of credentialRef as an input. The presence of an output schema reduces the need to explain return values, but parameter context remains a major gap.

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

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

Schema description coverage is 0%, so the description must compensate for the nine undocumented parameters. It only clarifies the behavior of 'secret' and 'credentialRef', leaving host, username, authKind, port, keyPath, and workspaceId unexplained. This is insufficient for an agent to correctly populate the parameters.

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

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

The description clearly states the tool's action: 'Creates a saved SSH connection through the Unfour command bus.' The verb 'creates' plus the resource 'saved SSH connection' precisely identifies the tool's function and distinguishes it from siblings like unfour.ssh.list_connections or unfour.db.create_connection.

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

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

The description implies usage for persisting an SSH connection, but it does not explicitly state when to use this tool versus alternatives such as unfour.ssh.exec for ad-hoc commands or unfour.db.create_connection for database connections. There is clear context but no explicit when/when-not guidance or named alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details: it is a 'soft-delete' (not permanent), and it describes a 'Guarded policy' requiring confirmation bound to workspace, connection, and revision, plus read-only rejection. This goes beyond the annotations and gives the agent a better sense of 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 concise at two sentences and front-loaded with the core action. The policy details in the second sentence are relevant but could be streamlined. It avoids unnecessary fluff and is appropriately sized for a destructive operation.

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 tool with 4 parameters, no schema descriptions, and no parameter semantics, the description is insufficient. It hints at confirmation requirements but does not explain the confirmation flow, what confirmation_text should be, or whether workspaceId is always required. Even though an output schema exists, an agent cannot confidently call this tool without guessing parameter values.

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

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

Schema coverage is 0%, so the description must compensate, but it only vaguely references 'confirmation' and 'workspace' without explaining individual parameters. It does not clarify the meaning of 'confirm' (boolean), 'confirmation_text', or how 'revision' maps to parameters. The description fails to provide the necessary semantic detail for correct invocation.

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 ('soft-deletes') and resource ('saved connection'), making the primary purpose clear. It distinguishes from generic delete tools by mentioning 'through CommandBus' and 'soft-deletes', but it does not explicitly differentiate from siblings like unfour.db.delete_connection or unfour.ssh.delete_task.

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 explicit guidance on when to use this tool versus alternatives. It mentions policy constraints (confirmation, read-only rejection) but does not state scenarios like 'use this for SSH connections' or compare to unfour.db.delete_connection. The usage context is implied by the tool name only.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds 'soft-deletes' and 'Guarded policy requires content-bound confirmation,' which provides extra context about the deletion being reversible and requiring confirmation. However, it doesn't detail what happens to associated data or the exact confirmation mechanism. No contradiction with annotations.

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

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

The description is very short (two sentences) and front-loaded with the main action. It is concise, but the second sentence about 'Guarded policy' is vague and could be more specific. Overall, it is efficient with no wasted words.

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 tool has 5 parameters, 0% schema coverage, and a destructive action, the description is insufficient. It does not explain the confirmation parameters, the workspaceId requirement, or the soft-delete behavior in detail. The output schema exists but the description doesn't clarify what the response will be. The tool is complex enough that more detail is 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 0%, so the description must compensate for parameter meaning. The description only mentions 'content-bound confirmation' but does not explain the purpose of taskId, confirm, workspaceId, confirmationText, or confirmation_text. The presence of both confirmationText and confirmation_text is confusing and unexplained. The description fails to clarify which parameters are required or how they interact.

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: 'Soft-deletes a saved SSH task.' It specifies the resource (SSH task) and the operation (delete), and the 'soft-deletes' qualifier adds nuance. It distinguishes from siblings like 'clear_task_runs' and 'cancel_task_run' by focusing on deleting a saved task, though it doesn't explicitly name 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?

The description mentions 'Guarded policy requires content-bound confirmation,' which implies a usage condition (confirmation needed) but does not explicitly state when to use this tool versus alternatives like 'clear_task_runs' or 'cancel_task_run'. It provides some context but lacks explicit when/when-not guidance.

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

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

Annotations are all false and carry no safety or behavioral signal. The description adds some context ('through the command bus', copies steps) but does not disclose side effects, whether a new task ID is generated, permissions needed, or what happens to the original task. This is minimal beyond annotations.

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

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

The description is one concise, front-loaded sentence. Every word contributes to defining the operation and its scope without unnecessary 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?

Given the low parameter coverage and false annotations, the description is too sparse for a mutation tool. It does not clarify required vs optional inputs, return behavior, or how duplicates are saved—leaving the agent to infer critical operational details despite an output schema being present.

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

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

Schema description coverage is 0%, and the description does not explain taskId or workspaceId. While taskId is reasonably inferable, workspaceId's role is unspecified, and no compensation is provided for the lack of parameter metadata.

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 ('Duplicates a saved SSH task') and explicitly scopes the scope of duplication ('and its steps'). It clearly distinguishes from sibling tools like save_task, run_task, and delete_task.

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 verb 'duplicates' implies the use case—copying an existing task—but there is no explicit guidance on when to choose this over save_task, get_task, or other related tools. No alternatives or exclusions are mentioned.

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