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?

The description adds substantial behavior beyond the sparse annotations: non-2xx responses return structured status/body data instead of MCP tool failure, sensitive headers/cookies/URL tokens/JSON body fields are masked, and environment-specific method restrictions are disclosed. This materially changes how an agent interprets results and plans calls, and nothing contradicts 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?

Four sentences, front-loaded with the core action and mode distinction, followed by the troubleshooting use case, environment restrictions, and behavior notes. It's dense but every sentence earns its place; the last sentence packs two behaviors (error handling and masking) into one clause, slightly reducing scannability.

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 complexity (11 params, two modes, environment-dependent behavior) and the existence of an output schema, the description covers the critical non-obvious behaviors: structured non-2xx responses, masking, and per-environment method rules. Minor gaps remain, such as not explaining that saved request scripts run or elaborating on the mutation implications, but annotations (readOnlyHint=false) partially cover 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 coverage is 100%, with each parameter already documented (e.g., timeoutMs defaults to 60000ms, requestId should be omitted when sending method/url directly). The description adds the two-mode framing and groups parameters as method/url/headers/query/body, but the schema already carries most of the semantic weight, so the description's added value is marginal.

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 a clear resource (API requests) with two precise modes: replaying a saved request by requestId or sending an ad-hoc request via method/url/headers/query/body. This distinguishes it from the sibling CRUD tools (create_request, update_request, delete_request, get_request), which manage request definitions rather than execute 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 gives an explicit use case ('Use it to reproduce API failures during agent troubleshooting') and explains environment-specific constraints (dev allows all methods, test marks mutating as write risk, prod restricts to GET/HEAD/OPTIONS). It doesn't explicitly name alternatives or say when not to use it, but the execution-vs-management distinction from siblings is clear enough.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the nuance that it 'Does not read table data', which is useful clarification beyond the annotations. However, it provides no additional behavioral details beyond that, so the added value is modest.

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, front-loaded sentence that clearly states the primary action and a crucial negative constraint. It contains no redundancy and is efficient in conveying the tool's scope.

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 has an output schema indicating it returns table structure, so the description need not explain return values. The description covers the purpose, the constraint, and the prerequisite of a saved connection. It is complete for an agent to call the tool correctly, though it lacks explicit error-handling context, which is not essential here.

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

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

The schema description coverage is 100%, so all four parameters are already documented in the schema. The description does not add any parameter-specific meaning or alternatives, meeting the baseline for high 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 explicitly states the tool 'Describes a table's structure (columns, types, nullability, primary keys)' for a saved database connection, and clarifies it 'Does not read table data'. This is a specific verb-resource pair that clearly distinguishes it from data-querying siblings like unfour.db.query_readonly and unfour.db.list_tables.

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 schema inspection and explicitly states it does not read table data, which hints at when not to use it. However, it does not name specific alternative tools or provide explicit when-to-use guidance, so it falls short of full explicitness.

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 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?

The annotations already declare readOnly, openWorld, idempotent, and destructive=false, covering the main behavioral aspects. The description adds that it lists tables and views, which is consistent but does not provide additional behavioral details beyond the annotations.

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

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

The description is composed of two clear and concise sentences. It efficiently states the purpose in the first sentence and a key constraint in the second, with no redundant or ambiguous wording.

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 that an output schema exists, the description need not explain return values. It adequately captures the main use case (listing tables/views for a saved connection) and the essential input constraints, making it complete for the tool's simple purpose.

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% (all parameters have descriptions). The description adds a semantic nuance by stating that connectionId must be a saved connection and not an ad-hoc string, which clarifies the expected input format beyond the schema's own description.

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

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

The description clearly states the action (lists), the resource (tables and views), and the context (saved database connection). It also explicitly notes that ad-hoc connection strings are not accepted, which helps distinguish it from potential 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 specifies that a saved connection is required and that ad-hoc connection strings are not accepted, providing clear conditions for use. However, it does not explicitly mention alternatives or when not to use this tool, though the constraints are sufficiently indicative.

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?

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 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.

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

Beyond the annotations, the description reveals important behavioral constraints: environment tier permissions, high-risk command examples, and the requirement to use a returned confirmation_text for guarded commands. These details add real safety context and do not contradict the annotations.

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

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

Three sentences, front-loaded with purpose, then usage context, then safety/confirmation behavior. The high-risk command list is long but directly actionable, so no sentence is wasted.

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 arbitrary command executor, the description covers environment gating, typical usage, and confirmation flow. It would be stronger with explicit mention of workspaceId/cwd/env/timeout behavior, but the presence of an output schema reduces the need to describe return 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?

With 0% schema description coverage, the description needed to compensate for all 9 parameters, but it only clarifies command, connectionId implicitly, and confirmation_text. Parameters like cwd, env, timeoutMs, workspaceId, confirm, and the duplicate confirmationText/confirmation_text are left unexplained, making the schema's 0% coverage a significant gap.

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

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

The description opens with a specific verb+resource: 'Executes one non-interactive SSH command on a saved connection.' This clearly differentiates it from diagnostic siblings like run_diagnostic and file-based tools like read_file/write_file/list_dir.

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 an explicit use case ('Use for dev/test repair loops after diagnostics identify a fix') and environment-specific guidance for dev/test/prod. It does not explicitly state when not to use the tool or name alternative siblings, so it falls just short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavior beyond annotations by revealing that the returned object includes steps and local connection binding, and that sensitive step-configuration fields are masked. No contradiction found.

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 with no filler. It front-loads the primary purpose in the first sentence and adds the essential security note in the second. Every word contributes 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 there is an output schema and the annotations describe the read-only, idempotent nature, the description is sufficiently complete for a get-by-id operation. It addresses the notable extra context (masking, binding, steps) without redundant return-format details. It could clarify workspaceId behavior, but the tool is simple enough to remain functional.

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 parameters at all. While 'Returns one SSH task' implies taskId is the selector, the optional workspaceId is entirely unexplained, leaving a semantic gap for that parameter.

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

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

The description states 'Returns one SSH task with steps and local connection binding,' which is a specific verb+resource+scope statement. It clearly differentiates from sibling tools like list_tasks (plural listing) and read_task_run_log by focusing on task configuration details.

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 this tool is used when a single SSH task's full details are needed, including steps and binding. It does not explicitly state when not to use it or name alternatives, but the context 'one SSH task' is sufficient to separate it from list/run/delete operations.

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

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

Annotations already declare this as read-only and idempotent, but the description adds crucial behavioral detail by explicitly stating that passwords, private keys, passphrases, and credential references are never returned. It also lists the exact fields that are returned, offering valuable transparency 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 two concise sentences that immediately state the action and provide useful details without any fluff. It is well-structured and front-loaded, making it easy to parse.

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 and the presence of an output schema plus safety annotations, the description is complete enough. It covers the purpose, the return contents, and the critical security behavior, providing all necessary context for an agent to invoke the tool 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?

The description references the workspace scoping in the phrase 'for a workspace', which implicitly points to the workspaceId parameter, but it does not explicitly detail the parameter's optionality or type beyond what the schema provides. With 0% schema description coverage, the description only partially compensates for the missing parameter documentation.

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

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

The description uses a specific verb 'Lists' with a clear resource ('saved SSH connections') and scope ('for a workspace'), making it easy to understand the tool's function. It also distinguishes itself from sibling tools that create or manage connections by focusing on the read-only list operation.

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 the tool is used when you need to list the saved SSH connections for a workspace. It does not explicitly mention alternatives or exclusions, but the purpose is self-evident and distinct from sibling tools, providing adequate 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description only needs to add extra context. It does so by noting the operation is 'bounded' and that results are structured only when the remote find utility is available, which are useful behavioral details beyond the annotations. The description does not contradict any annotation.

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

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

The description is two sentences long, front-loaded with the main action, and contains no wasted words. It efficiently communicates the core purpose and a key behavioral condition without 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?

While the output schema covers return structure, the description lacks clarity on parameter usage, the meaning of 'bounded,' and what happens when the find utility is unavailable. These gaps are significant given 0% schema description coverage and the tool's reliance on a remote utility. The description could be more complete with explicit parameter notes and fallback behavior.

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

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

The schema description coverage is 0%, so the description must compensate by explaining key parameters like path and limit. It does not mention any parameter meanings or usage requirements. The only hint is 'bounded' possibly hinting at limit, but it is not explicit. This is insufficient for a 5-parameter tool with zero schema explanations.

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: 'Lists a bounded remote directory through SSH and returns structured entry summaries when the remote find utility is available.' It uses a specific verb (lists), identifies the resource (remote directory), and adds a conditional detail about the find utility, distinguishing it from general exec or file operations.

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

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

The description implies this tool is for listing directories, but it does not explicitly state when to use it over alternatives like exec or read_file. It does mention 'Safe in dev/test/prod,' which hints at safe execution contexts, but lacks explicit when-not and alternative guidance. This is adequate but not thorough.

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

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

Annotations already declare the tool safe (readOnlyHint=true, destructiveHint=false), and the description adds meaningful behavioral disclosure beyond those flags: sensitive commands 'are excluded or replaced with [redacted command]', results are 'workspace-scoped', and fields are returned 'when recorded'. The redaction behavior and scope guarantees are exactly the kind of non-obvious context agents need and are not inferable from annotations.

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

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

Four tight sentences and roughly 90 words cover purpose, return shape, scope guarantees, redaction policy, and the follow-up workflow. The first sentence front-loads the core purpose, and no sentence is wasted on restating annotations or schema text.

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

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

For a read-only tool with 6 optional (100% schema-documented) parameters, an output schema, and rich annotations, the description covers the remaining gaps: what fields come back, what is excluded (terminal buffers, session logs), redaction behavior, and the recommended post-step (drafting a task). No material behavioral question is left unaddressed.

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

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

Schema description coverage is 100%, so the rubric baseline is 3. All six parameters are individually documented with type, constraints (max 200, RFC 3339 format), and edge-case behavior ('Unknown or out-of-workspace connections return an empty list'). The description adds workspace-scoping and redaction context, but no parameter-level semantics that meaningfully exceed what the schema already provides, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource+scope: 'Lists structured SSH command history for the current MCP workspace,' and enumerates the returned fields (connection, command, executedAt, cwd/exitCode/durationMs). It clearly differentiates from close siblings like unfour.api.list_history and unfour.activity.list by scoping to SSH commands and explicitly ruling out terminal buffers/session logs.

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

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

Explicit when-to-use guidance is present: 'Use this to inspect recent host activity, then draft a reusable SSH Task for the user to confirm,' along with a pointed when-not instruction: 'Do not call unfour.ssh.save_task unless the user explicitly asks to save the draft.' It could be stronger by naming read-alternatives (e.g., when to prefer activity.list), but the primary workflow and one key guardrail are 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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by clarifying the return specifically contains 'saved run summaries' and explicitly excludes 'local log paths', which is a meaningful behavioral detail beyond the annotations. It does not repeat the annotation info but enriches the agent's understanding of the data 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?

The description is a single sentence of 15 words, immediately front-loading the action ('Lists') and object ('saved run summaries') and adds one critical exclusion at the end. Every word earns its place with 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 this is a read-only list operation with a wealth of sibling context (like list_tasks, exec, read_file), the description provides solid coverage of the core purpose. The presence of an output schema (even though not shown) reduces the need to describe return values. The only gap is the lack of parameter semantics, but for a simple listing tool with two parameters, the description adequately serves an agent's basic need without padding.

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 fails to explain the purpose of 'taskId' and 'workspaceId'. While 'taskId' might be inferable from the tool name, 'workspaceId' is optional and its role is unclear. The description does not clarify whether workspaceId is needed for filtering or required in any context, and no parameter details are provided to compensate for the schema's lack of 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 specific language: 'Lists saved run summaries for one SSH task' with the verb 'Lists', a specific resource ('saved run summaries'), and scope ('for one SSH task'). It also differentiates from siblings by noting it does not expose 'local log paths', which is useful given the related tool `unfour.ssh.read_task_run_log`.

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 a read-only, non-destructive listing use case with 'saved run summaries'. It gives context that local log paths are not exposed, which helps the agent know this is not the tool for retrieving full logs. However, it does not explicitly name an alternative or state when NOT to use it in favor of a sibling tool, though it comes close.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds that it lists 'summaries' which implies a high-level view, but does not disclose what fields are included, whether it returns all tasks or paginated, or any specifics about the output format. With annotations covering the safety, the description provides minimal additional behavioral context, so a 3 is appropriate.

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

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

The description is a single sentence, very concise, and directly states the purpose. No fluff or redundant information. It's appropriately brief for 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 tool's simplicity (one parameter, read-only list operation), the description might be sufficient. However, there is an output schema (not shown) that could provide details, and the description does not mention any pagination, filtering, or ordering. It also doesn't clarify the difference between 'task summaries' and other task-related tools. The presence of sibling tools like list_task_runs suggests there is nuance missing, so it's not fully complete.

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

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

There is one parameter, workspaceId, and the schema coverage is 0% (the property description is empty). The description says 'for a workspace' which implies workspaceId is needed, but it doesn't clarify the semantics of the workspaceId (e.g., where to find it, if it's optional, or if it filters by workspace). With no param descriptions in the schema, the description should compensate, but it provides only a vague hint. Since it's the only parameter and the description mentions workspace, it adds minimal value, but not enough for a higher score.

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 it lists saved SSH task summaries for a workspace, using the verb 'list' with a specific resource (SSH task summaries) and a scope (workspace). However, it does not differentiate from sibling tools like unfour.ssh.list_task_runs or unfour.ssh.get_task, so it could be confused with those.

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

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

No guidance on when to use this tool vs alternatives. The description does not mention that this tool is for listing task summaries (metadata) as opposed to task runs or individual task details, nor does it mention any preconditions or context. Sibling tools list_task_runs, get_task, and others exist but the description offers no differentiation.

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 sparse (all hints false), so the description carries the burden of disclosing behavior. It states it returns a diff without file content, and explains confirmation requirements and prod blockage. This adds useful behavioral context beyond the annotations, though it doesn't detail side effects or error handling.

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 then environment-specific rules. No filler or redundancy; every part 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 the tool's complexity (9 params, output schema, environmental constraints), the description provides a solid high-level overview but lacks parameter semantics and fails to address edge cases like searches with no match or multiple matches beyond confirmation. The output schema covers return values, but the description doesn't explain the confirmation flow or the distinction between confirmationText and confirmation_text fields.

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 any of the 9 parameters beyond indirectly mentioning search and replace. It fails to clarify the meaning of confirm, confirmationText, confirmation_text, timeoutMs, workspaceId, or connectionId, leaving the agent without guidance for these fields.

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 applies a small search/replace patch to a remote file via SSH and returns a diff summary. It uses a specific verb (applies) and resource (remote file via SSH), and distinguishes itself from sibling tools like unfour.ssh.write_file and unfour.ssh.read_file by focusing on patching rather than full writes or reads.

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 environment-specific usage rules: dev allows single-match patches, test/system/multi-match require confirmation, prod is blocked. This gives clear context on when it's appropriate and when confirmation is needed, though it doesn't explicitly contrast with alternatives like write_file or exec.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: 'output is capped and line-redacted by the SSH engine' and 'Sensitive paths may still be blocked by connection or OS permissions.' This gives the agent crucial expectations about limits and failure modes.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds distinct value (use cases, environment allowance, output/security behavior). No wasted words or repetition of schema/annotation fields.

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

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

Given 7 parameters and 0% schema description coverage, the description could have been more thorough about parameter semantics. However, the existence of an output schema covers return value details, and the description explains output caps, redaction, and permission issues. It is reasonably complete for a read-only tool, but not fully exhaustive.

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 hints at parameter roles via 'bounded remote file slice or tail' (limit/offset/tailLines) and 'through SSH' (connectionId), but it does not explain timeoutMs, workspaceId, or provide per-parameter detail. The compensation is partial, warranting a mid-range score.

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 'Reads a bounded remote file slice or tail through SSH' and explicitly mentions use cases ('logs and config inspection'). It distinguishes itself from siblings like write_file, exec, and read_task_run_log by specifying the bounded file read behavior.

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

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

Provides clear context: 'Useful for logs and config inspection' and notes that 'Dev/test/prod allow ordinary reads.' However, it does not explicitly mention when not to use it or compare to similar tools like read_task_run_log, so it lacks full exclusion 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?

The annotations already indicate a safe read-only operation, and the description adds valuable behavioral details: the log is capped, configured secret inputs are redacted, and the local log path is omitted from the response. This exceeds the annotation-only baseline without contradicting it.

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 extremely concise: two short sentences, each adding distinct information. There is no filler or repetition of the structured schema and annotations.

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

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

Given the tool's low complexity, the required runId, and the presence of an output schema, the description covers the primary behavioral aspects. Minor gaps remain around the meaning of 'capped' and the role of workspaceId, but these are modest for a simple read-only log 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 0%, so the description should compensate by explaining the parameters. It does not explain how runId or workspaceId should be used. The parameter names are somewhat self-explanatory, but the description adds no semantic detail about them.

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

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

The description uses a specific verb and resource: 'Reads a capped SSH task run log.' This clearly distinguishes it from sibling tools like listing or running tasks, and the title aligns exactly with the described operation.

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 intended use case is implied by the name and description: retrieve the run log for an SSH task run. However, there is no explicit guidance about when to use this rather than related tools such as list_task_runs or get_task, and no mention of 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?

Annotations already mark this as a non-read-only, non-idempotent write operation. The description adds useful context by stating it reorders all active tasks and requires the exact task set. However, it does not disclose failure behavior, stale-task handling, or workspaceId requirements.

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

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

Exactly two sentences with no filler; the core operation and the critical constraint are both present and front-loaded. 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?

The description captures the main invariant and scope well, and an output schema is present, so the return value need not be described. Minor gaps remain around workspaceId semantics and edge cases like stale taskIds, but overall the tool is adequately specified for selection and invocation.

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

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

With 0% schema description coverage, the description supplies the essential meaning for taskIds: it must be the exact active task set and its order determines the new order. However, workspaceId is left undefined in both the schema and description, so the description only partially compensates for the coverage gap.

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

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

Clearly states it reorders active SSH tasks in a workspace, with a precise scope and the key constraint that taskIds must be the exact active set. This distinguishes it from sibling task tools like delete_task, run_task, and save_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 description implies the agent must obtain the current active task set before calling, but it does not explicitly say when to prefer this tool over other task operations or when not to use it. Usage guidance is mostly implicit through the 'exact active task set' constraint.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context about being read-only and restricted to allowlisted diagnostics, which aligns with annotations. No contradictions; only minor gap is not detailing exact behavior on failures or non-allowlisted commands.

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, first states action and result, second provides safety and alternative. Zero fluff, all information 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?

With output schema present and annotations covering safety, the description covers purpose, scope, restrictions, and alternatives. Even with moderate tool complexity, it is complete for the agent to decide correct usage.

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 carries the burden. It mentions connectionId and command implicitly via 'saved SSH connection' and 'diagnostic command', but doesn't explain timeoutMs or workspaceId. Baseline 3 is appropriate since it adds some meaning but not full compensation for all 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 'Runs a single read-only diagnostic command' on a saved SSH connection, with specific output ('returns captured stdout/stderr'). It distinguishes itself from unfour.ssh.exec by explicitly contrasting scope ('allowlisted diagnostics' vs broader execution).

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

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

Explicitly says 'Safe in dev/test/prod for allowlisted diagnostics' and directs users to unfour.ssh.exec for broader execution, naming the alternative and clarifying when to use this tool vs not.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description enhances this by clarifying the execution policy behavior: blocked on production/read-only and requiring content-bound confirmation on guarded systems because tasks may execute commands or transfer files, adding genuine value about side effects without contradicting 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?

Three sentences with essential information about execution policy and safety delivered efficiently. Each sentence serves a purpose, though the 'selected saved connection' phrasing is slightly verbose.

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

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

For a task-runner with nested objects and an output schema, the description gives appropriate context about side effects and policy restrictions. The existence of an output schema reduces the need to document return values, and the description covers the ambiguity of what 'saved task' means in terms of policy constraints effectively.

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 focuses on the tool's behavior rather than explaining individual parameters. The description clarifies the 'inputs' concept generally by noting tasks may execute commands or transfer files, but with 8 parameters and no explanation of confirm vs confirmationText vs confirmation_text (a likely inconsistency worth mentioning) or secretInputNames, the description could have compensated more for the lack of 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 starts a saved SSH task on its selected saved connection, using the specific verb 'starts' with the resource being the saved SSH task/connection. It partially distinguishes from siblings by explaining the policy implications (production/read-only blocks execution, guarded needs confirmation), which relates to when operations proceed.

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

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

While it doesn't name alternatives explicitly, the policy language tells the agent when execution will be blocked or need confirmation, which is crucial for an agent deciding to call this. It provides useful context about the execution context even though it could be more explicit about when to use this versus other SSH sibling tools.

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