SSH MCP Server

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

No annotations provided, so description carries full burden. It successfully discloses validation behavior ('Validates key format and strength'), policy enforcement ('Enforces TTL limits'), authorization requirements ('ADMIN role'), and risk profile ('high'). Missing idempotency guarantees and specific side effects beyond registration.

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?

Five distinct sentences, each earning its place: action, validation, enforcement, authorization, risk. Information is front-loaded with the core action and structured logically from functional description to security constraints.

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 covers behavioral and security context well for a complex mutation tool, and an output schema exists (relieving return value documentation), the 0% parameter schema coverage combined with insufficient parameter explanation in the description leaves significant gaps in required documentation for a 5-parameter 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?

With 0% schema description coverage, the description must compensate heavily. It provides context for 'ttl_seconds' (TTL limits), 'approval_request_id' (prior approval), and 'public_key' (key format validation), but fails to explain required parameter 'user_name' or optional 'reason' field semantics beyond their titles.

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 clearly states the tool 'Register[s] a new SSH public key' with specific scope (policy checks included). It effectively distinguishes from sibling 'remove_ssh_key' and relates to approval workflow tools (approve_request, request_approval) by mentioning registration vs. removal and approval requirements.

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 states prerequisites: 'Requires ADMIN role and prior approval' and 'Risk level: high'. This signals when the tool is appropriate (admin tasks with existing approval) and implies the workflow sequence (approval first), though it doesn't explicitly state 'do not use without approval' or contrast with non-admin 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?

No annotations provided, so description carries full burden. Effectively discloses critical behavioral traits: high risk level, that it grants execution permission, and two-party mode requirements. Does not mention if approval is reversible or immediate 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?

Three sentences, each earning its place: purpose first, operational constraint second, risk warning third. No redundant or filler text. Appropriately 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?

Adequate for a high-risk mutation tool given the output schema exists (covering return values). However, gaps remain: with 0% schema coverage, parameters lack documentation in both schema and description, and there's no mention of prerequisite steps (e.g., obtaining tokens from list_pending_approvals).

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% (no parameter descriptions), yet the description adds no semantic information about 'request_id' or 'approval_token'. Relies entirely on parameter names being self-explanatory, providing no context on where the approval_token originates or its format.

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

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

States the specific action (approve) and resource (pending approval request) clearly. Distinguishes sufficiently from sibling 'request_approval' through the opposite verb, though could explicitly reference the relationship.

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 a specific operational constraint ('In two-party mode, the approver must be a different user from the requester'), but lacks explicit guidance on when to use this versus alternatives or prerequisites like obtaining the approval_token.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates risk level and confirmation requirements, but omits critical operational details like whether cancellation is immediate or graceful, whether partial results are preserved, or what the output schema contains.

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

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

The description is optimally concise with two information-dense sentences. The primary action is front-loaded in the first sentence, while risk metadata follows in the second. No filler or redundant text is present.

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

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

Given the tool's simplicity (single required parameter) and existence of an output schema, the description adequately covers the core operation and risk profile. However, completeness suffers from the lack of parameter documentation and absence of behavioral details about the cancellation mechanism itself.

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 has 0% description coverage (job_id has only a title). The description fails to compensate by not mentioning the parameter at all, nor explaining where to obtain valid job IDs (e.g., from list_background_jobs). While the parameter intent is inferable from the tool name, this gap leaves the agent without guidance on job_id format or source.

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 specific action (Cancel) and resource (running background job), distinguishing it from sibling tools like list_background_jobs, poll_background_job, and run_ssh_command_background. However, it doesn't specify what types of background jobs (e.g., SSH commands, cert operations) are cancellable.

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 risk level ('medium') and explicitly states that user confirmation is required, which guides cautious usage. However, it lacks explicit guidance on when to cancel versus let jobs complete, and doesn't mention that job_id values likely come from list_background_jobs or run_ssh_command_background siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully indicates the read-only nature and risk level, but lacks details about log content, retention periods, or pagination behavior beyond the 'last N' limitation.

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 appropriately front-loaded with the core purpose in the first sentence, followed by safety metadata. Every sentence adds value with no redundancy or waste.

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

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

Given the tool's simplicity (1 optional parameter) and the existence of an output schema, the description provides minimum viable information. However, with zero schema annotations, it should explicitly document the parameter's default value and optional status.

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%, requiring the description to compensate. It partially compensates by mapping 'last N' to the parameter's purpose, but fails to document that the parameter is optional, has a default value of 50, or specify valid ranges/constraints.

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 specific action (Return) and resource (audit log entries), distinguishing it from sibling SSH and approval management tools. However, it doesn't explicitly differentiate from other list/retrieve operations like list_background_jobs.

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 safety information ('Read-only', 'Risk level: low') but offers no guidance on when to use this tool versus alternatives, prerequisites, or conditions where it might not be 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?

No annotations provided, but description compensates well with explicit risk disclosure ('Risk level: low', 'safe', 'no secrets'). Clearly signals this is a read-only operation that doesn't expose sensitive data.

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

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

Two efficient sentences with zero waste. Front-loaded with the core action and safety constraints. The em-dash effectively separates the scope from the safety assertion.

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?

Adequate for a single-parameter tool with existing output schema (no return value description needed). However, the undocumented host_id parameter leaves a significant gap given the schema lacks descriptions.

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 has 0% description coverage (host_id lacks description), and the description fails to compensate. No mention of what host_id represents (UUID, hostname, IP) or its relationship to the operation.

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?

Excellent specificity with verb 'Get', resource 'host metadata', and concrete examples (OS, uptime, kernel). The 'safe' qualifier effectively distinguishes this from sibling execution tools like run_ssh_command.

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

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

Implies usage through 'safe' and 'no secrets' constraints, suggesting when to prefer this over command execution tools. However, lacks explicit when-to-use guidance or named alternatives (e.g., vs run_ssh_command).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates authorization requirements (ADMIN role), prerequisites (prior approval), risk profile (high), and operational characteristics (signed by local CA, tight TTL). It appropriately signals this is a sensitive write operation.

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

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

The description is optimally structured with the purpose front-loaded in the first sentence, followed by implementation details, requirements, and risk assessment. Every sentence delivers unique value without redundancy 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?

Given the tool's complexity (5 parameters, security-sensitive mutation) and presence of an output schema, the description adequately covers operational context and risk. The main gap is parameter documentation, which should have been addressed given the 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%, requiring the description to compensate. It partially succeeds by implying semantics for 'user_id' ('for a user'), 'ttl_seconds' ('tight TTL'), and 'approval_request_id' ('prior approval'). However, it fails to explain 'principals' (SSH-specific concept) or 'justification' (audit purpose), leaving critical parameters undocumented.

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

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

The description opens with a specific verb ('Issue') and resource ('short-lived SSH certificate'), clearly defining the tool's scope. It distinguishes itself from sibling tools like 'add_ssh_key' by specifying 'certificate' and from 'revoke_cert' by specifying 'Issue'.

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 states prerequisites ('Requires ADMIN role and prior approval'), implying the workflow sequence with 'request_approval'. It also flags 'Risk level: high' to guide cautious usage. However, it lacks explicit guidance on choosing between this and 'add_ssh_key' for different authentication scenarios.

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

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

Since no annotations are provided, the description carries full burden of safety disclosure. It explicitly states 'Risk level: low (read-only)' and clarifies the scope includes both running and completed jobs. Output schema exists per context signals, so return format explanation is not required.

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

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

Extremely concise two-line structure: first line states purpose, second line states risk level. Zero redundancy, front-loaded with critical 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?

Adequate for a zero-parameter list operation with output schema present. Covers purpose, scope, and safety profile. Minor gap: could mention pagination behavior or relationship to poll_background_job sibling.

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

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

Zero parameters present (schema is empty object), establishing baseline of 4. No parameter documentation needed.

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 provides specific verb ('List') + resource ('background jobs') + scope ('running + completed'), clearly distinguishing from sibling tools like poll_background_job or cancel_background_job.

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?

Lacks explicit when-to-use guidance versus alternatives like poll_background_job. The scope 'all' implies usage, but does not explicitly state when to prefer listing all jobs versus polling a specific job.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It successfully adds critical security context: authentication level requirements and explicit 'Risk level: low' classification. It could be improved by mentioning idempotency or caching behavior, but covers the essential safety profile.

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 tightly constructed sentences with zero redundancy. Purpose is front-loaded in the first sentence, followed by authentication context and risk classification. Every sentence earns its place with no filler content.

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

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

For a zero-parameter list operation with an output schema present (making return value description redundant), the description is complete. It appropriately focuses on security context (auth and risk level), which is critical for SSH infrastructure tools, rather than repeating structural information available in the schema.

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

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

The tool has zero parameters (empty schema), which per evaluation rules establishes a baseline score of 4. No parameter documentation is required or expected in the description text.

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

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

The description uses specific verb 'List' with clear resource 'allowed SSH hosts' and explicitly scopes the output to 'metadata (labels, roles, description)'. This effectively distinguishes it from siblings like get_host_facts (which likely retrieves detailed facts for a specific host) and run_ssh_command (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?

Provides clear context about authentication requirements ('No authentication required beyond basic identity'), which helps the agent understand prerequisites for invocation. However, it does not explicitly name alternative tools or provide explicit when-not-to-use guidance, stopping short of a perfect score.

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

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

With no annotations provided, the description carries full disclosure burden and explicitly states 'Risk level: low (read-only)', informing the agent this is a safe operation. It could improve by mentioning pagination behavior or result limits, but adequately covers the critical safety profile.

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 zero waste: first states the operation, second discloses risk classification. Information is front-loaded and appropriately sized for a zero-parameter tool.

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

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

Given zero parameters and existence of an output schema (per context signals), the description is complete. It covers the operation purpose and safety level without needing to document return values or complex parameter interactions.

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?

Per evaluation rules, zero parameters warrants a baseline score of 4. The description appropriately does not invent parameter semantics where none exist in the empty 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 uses specific verb 'List' with clear resource 'pending approval requests', clearly distinguishing it from sibling tools 'approve_request' (action) and 'request_approval' (creation). The scope 'all' precisely defines the operation's breadth.

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

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

While the description implies usage through clear naming (list vs approve), it lacks explicit when-to-use guidance or comparison with alternatives like 'approve_request'. The agent must infer when listing is preferable to other approval-related 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?

No annotations provided, so description carries full burden. Discloses 'Risk level: low' and explains template contents (pre-approved patterns, allowed parameters, roles), providing necessary behavioral context for a security-sensitive SSH tool.

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

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

Four sentences with zero waste: purpose (sentence 1), template contents (sentence 2), usage instruction (sentence 3), risk disclosure (sentence 4). Well front-loaded and appropriately sized.

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?

Tool has output schema (documented separately), so return values need not be described. For a zero-parameter list operation, description adequately covers purpose, output usage (template_id), and risk profile.

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

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

Zero parameters present, meeting the baseline score of 4. Schema is empty object with 100% coverage; no parameter documentation needed.

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

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

Specific verb 'List' with clear resource 'command templates'. Explicitly links to sibling tool 'run_ssh_command', distinguishing it from other list operations like list_hosts or list_background_jobs.

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 explicit guidance: 'Use the template_id when calling run_ssh_command', establishing the relationship with the sibling execution tool. Lacks explicit 'when not to use' exclusions, but context is clear.

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

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

With no annotations provided, the description carries the full burden and successfully discloses key behaviors: the incremental nature of returns ('new stdout since last poll'), the read-only safety profile ('Risk level: low'), and the specific return contents (stdout, status, exit code). Minor gaps remain regarding error cases or rate limits.

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

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

Three sentences with zero waste. Purpose is front-loaded ('Read accumulated output...'), followed by return value specifics, then risk classification. Each sentence adds distinct 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?

Appropriate for a single-parameter polling tool. The description explains return values even though an output schema exists (helpful redundancy). Minor gap: does not mention that job_id typically comes from run_ssh_command_background or list_background_jobs.

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 has 0% description coverage (only title 'Job Id'). The description mentions operating on a 'background job' which implicitly maps to the job_id parameter, but does not explicitly describe the parameter semantics, format, or where to obtain valid job IDs.

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 specific action (Read) and resource (accumulated output and status of a background job). It effectively distinguishes from siblings like cancel_background_job (mutation vs read) and list_background_jobs (listing all vs polling specific job 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 phrase 'new stdout since last poll' implies iterative usage for monitoring, but there is no explicit guidance on when to use this versus list_background_jobs, or that it should be used repeatedly to track jobs started by run_ssh_command_background.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates authentication requirements (ADMIN role), workflow prerequisites (prior approval), and safety profile (high risk). It omits whether the operation is reversible or if it affects existing SSH sessions.

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 zero waste: action definition, permission requirements, and risk warning. Information is front-loaded with the core purpose in the first sentence.

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

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

Adequate for a high-risk administrative tool given the existence of an output schema (covering return values), but gaps remain in parameter documentation. With 0% schema coverage, the description should explicitly document all three parameters and their relationships to the approval workflow.

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

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

Schema description coverage is 0%, requiring the description to compensate. While 'key_id' is mentioned explicitly and 'prior approval' loosely implies 'approval_request_id', the 'reason' parameter is completely undocumented. The relationship between the approval workflow and the approval_request_id parameter is not explicitly stated.

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 the specific action 'Revoke / remove' targeting the 'SSH key' resource, using 'key_id' as the identifier. This clearly distinguishes it from sibling tool 'add_ssh_key' and other SSH management 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?

States explicit prerequisites ('Requires ADMIN role and prior approval') and risk profile ('Risk level: high'), which helps determine when the tool is appropriate. However, it doesn't explicitly map the 'prior approval' requirement to the 'approval_request_id' parameter or reference sibling 'approve_request' as the prerequisite step.

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

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

With no annotations provided, the description carries full disclosure burden. It successfully states the operation is safe (risk level: low), returns a request_id and one-time approval_token, and specifies the token presentation requirement. Could improve by mentioning expiration or who can approve, but covers core behavioral traits well.

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?

Five sentences with zero waste: purpose front-loaded, followed by return values, workflow steps, and risk assessment. Each sentence earns its place. Well-structured for quick parsing.

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 approval workflow is conceptually complete and output schema exists (reducing need for return value description). However, the complete absence of parameter documentation for 4 fields—especially 2 required ones—creates a critical gap for an agent trying to construct valid invocations.

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% (only titles provided). The description mentions 'Tier 2 operation' which gives semantic context to the 'action' parameter, but provides no guidance on 'justification' format, 'host_id' usage, or 'ticket_ref' purpose. With zero schema descriptions, the description fails to compensate for undocumented required 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?

Clearly states the tool requests approval for 'privileged (Tier 2) operations,' using specific verb (request) and resource (approval). The 'Tier 2' qualifier and distinction from sibling 'approve_request' (via workflow description) makes the 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?

Excellent workflow guidance: explains the token must be presented to an approver and request_id passed to the privileged tool. Describes the multi-step process clearly. Lacks explicit 'when not to use' or direct comparison to sibling 'approve_request,' but the flow description provides strong implicit 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?

No annotations provided, so description carries full burden. Discloses destructive effects (PEM files deleted), side effects (added to revocation list), authorization requirements (ADMIN role), and workflow constraints (prior approval). Strong coverage of operational 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?

Well-structured with clear paragraph breaks: action statement, side effects, requirements, and risk. Every sentence conveys distinct information (effects, auth, risk). Efficient length with no 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?

Adequate for a high-risk administrative tool with output schema present (no return value documentation needed). Covers authorization, side effects, and risk. Minor gap: could explicitly document the three parameters given 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 has 0% description coverage. Description implies 'cert_id' through the revocation action and 'approval_request_id' through 'prior approval' mention, but does not explicitly document parameters or explain the 'reason' field. Provides baseline semantic context for the operation.

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

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

Opens with specific verb+resource ('Revoke an issued SSH certificate') and distinguishes from sibling 'issue_cert'. Clearly defines scope by stating revoked certs are added to revocation list and PEM files deleted.

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 states prerequisites ('Requires ADMIN role and prior approval') and risk context ('Risk level: high'), which guides when to invoke. Lacks explicit comparison to sibling alternatives like 'issue_cert' or 'remove_ssh_key'.

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

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

With no annotations provided, the description carries full behavioral disclosure burden and succeeds admirably. It discloses validation behavior ('validated against per-template regex rules'), security processing ('Output is automatically redacted for secrets'), safety requirements ('requires user confirmation in VS Code'), and connection state management ('reuse a persistent 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?

Information density is high with zero waste. The structure flows logically: purpose → prerequisite → concrete examples → constraints → validation → security → optimization → risk. Every sentence provides unique value not available in the schema, and the examples efficiently illustrate parameter patterns for the polymorphic 'params' field.

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 complex operation involving SSH execution, template registries, dynamic parameters, and security redaction, the description is remarkably complete despite zero schema annotations. It covers discovery workflows, security constraints, output processing, and connection reuse patterns. Since an output schema exists, the description appropriately omits return value details.

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?

Given 0% schema description coverage (only titles like 'Host Id'), the description fully compensates by explaining all four parameters through context and examples. It illustrates 'params' structure with concrete JSON examples (e.g., {"service": "docker"}), explains 'session_id' sourcing from ssh_connect, and clarifies 'template_id' discovery via list_templates.

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 precise action ('Execute a pre-approved command template') and clearly identifies the target resource ('target host'). It effectively distinguishes this tool from arbitrary command execution tools by emphasizing the 'pre-approved' constraint and template registry requirement, setting clear boundaries against siblings like direct SSH tools.

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

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

Provides explicit workflow guidance by directing users to 'Use list_templates to discover available template_ids' and referencing 'ssh_connect' for obtaining session_id. While it establishes the prerequisite chain clearly, it does not explicitly contrast with 'run_ssh_command_background' to guide when to use foreground versus background execution.

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?

No annotations provided, so description carries full burden. Discloses non-blocking behavior, immediate return of job_id, security model (template-only), and risk level (medium, requires confirmation). Could improve by mentioning job persistence or timeout 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?

Five sentences, each earning its place: purpose, return value, workflow tools, security context, and risk level. Front-loaded with the core action and efficiently structured.

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?

Has output schema (per context signals), so omitting detailed return value explanation is acceptable. However, with 3 parameters at 0% schema coverage and only 'template' mentioned in description, the parameter documentation is incomplete for a tool 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 has 0% description coverage. Description mentions 'template command' implying template_id's purpose, but fails to explain host_id (hostname vs UUID?) or params structure (key-value substitutions?). With zero schema coverage, the description must compensate more for the three 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?

States specific action (Start), resource (template command), and key behavioral trait (non-blocking/background). Distinguishes from sibling 'run_ssh_command' by emphasizing the async nature and immediate job_id return.

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

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

Explicitly names three related tools for the job lifecycle workflow: 'poll_background_job to read output', 'list_background_jobs to see all jobs', and 'cancel_background_job to stop'. Also references sibling 'run_ssh_command' for security model comparison.

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

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

With no annotations provided, the description carries full burden and discloses critical behavioral traits: scope constraints (allowed_paths), validation rules (blocked extensions), prerequisites (justification required), and risk profile (medium risk requiring user confirmation).

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?

Excellent structure: single sentence stating purpose followed by bullet-like constraints. Every line provides essential safety or constraint information. No redundant or filler text.

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

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

For a destructive operation with 4 parameters and an output schema, the description adequately covers safety-critical aspects (constraints, risk, confirmation requirements). Missing explicit parameter semantics, but the output schema handles 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?

Schema has 0% description coverage. The description mentions 'Requires a justification' which maps to the justification parameter, but provides no semantics for host_id, remote_path (format/path rules), or session_id (when to use optional session vs new connection).

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 specific action (Delete), resource (remote file), and method (via SFTP). It effectively distinguishes from siblings like sftp_list_directory, transfer_file, and run_ssh_command by specifying the exact 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?

Provides clear constraints on usage (allowed_paths only, blocked extensions enforced, justification required) and risk level (medium). However, it does not explicitly name alternatives or state when to prefer run_ssh_command for deletion instead.

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

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

With no annotations provided, the description carries the full burden and successfully discloses 'Risk level: low (read-only)' and the allowed_paths access restriction. However, it omits error behavior for invalid paths or connection 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?

Three sentences efficiently convey the core action, access constraints, and safety profile without redundancy. The most critical information ('List files...') 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 the presence of an output schema, the description appropriately omits return value details. However, with zero parameter schema coverage and no mention of the authentication/connection model (host_id/session_id relationship), the description leaves significant gaps for a 3-parameter 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%, requiring the description to compensate. While 'remote path' maps to the remote_path parameter, the description fails to explain host_id (likely referencing list_hosts) or session_id (optional connection reuse), leaving two of three parameters undocumented.

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

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

The description opens with a specific verb ('List') and clear resource ('files and directories at a remote path'), immediately distinguishing it from sibling tools like sftp_delete, transfer_file, and run_ssh_command.

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 the important constraint 'Only paths within the configured allowed_paths are accessible,' which defines operational boundaries, but lacks explicit when-to-use guidance or comparisons to alternatives like transfer_file or sftp_delete.

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

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

No annotations provided, so description carries full burden. Discloses key behavioral traits: keepalive probes, auto-close after idle timeout, return value semantics (session_id), and security posture ('Risk level: low'). Does not cover authentication requirements or error conditions.

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

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

Four sentences with zero redundancy. Front-loaded with purpose ('Open...'), followed by return value, lifecycle behavior, and risk level. 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?

Appropriate for tool complexity (single parameter, output schema exists). Covers connection lifecycle management and integration points with sibling tools. Could mention authentication prerequisites given SSH context, but acceptable without.

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 has 0% description coverage for the single 'host_id' parameter. Description mentions 'to a host' but fails to specify what host_id represents (IP address, hostname, or reference from list_hosts?), acceptable formats, or constraints. Insufficient compensation for schema 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?

Specific verb ('Open') + resource ('persistent SSH session') + scope ('to a host'). Explicitly distinguishes from sibling tools by stating it returns a session_id for 'run_ssh_command' and 'transfer_file', establishing the persistent vs. one-off usage pattern.

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 guidance by naming specific sibling tools (run_ssh_command, transfer_file) that consume the output. Mentions 'reuse the connection' implying when to choose this over stateless alternatives. Lacks explicit 'when not to use' exclusions (e.g., short-lived commands).

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

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

With no annotations, the description carries full burden but only adds 'Risk level: low'. It fails to disclose whether the close is graceful, what happens to running commands, or what the output schema contains (despite output schema existing).

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

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

Extremely concise with only two sentences. Front-loaded with the core action. The risk level statement earns its place as the only behavioral hint provided.

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 zero annotations, zero schema coverage, and the existence of an output schema, the description is too sparse. It should explain the session_id parameter and ideally reference the return value or success confirmation.

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 has 0% description coverage, yet the description does not compensate by explaining the session_id parameter, its format, or how to obtain it (e.g., from ssh_connect or ssh_list_sessions).

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 ('Close') and resource ('persistent SSH session'), clearly distinguishing it from siblings like ssh_connect, ssh_list_sessions, and run_ssh_command.

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

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

Provides no explicit 'when to use' guidance or workflow context (e.g., 'use when finished with a session'), though the purpose implies cleanup. Does not mention prerequisites like requiring an existing session from ssh_connect.

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?

No annotations are provided, so the description carries the full disclosure burden. It adds valuable safety context ('Risk level: low') and resource constraints ('remaining connection slots'), but omits other behavioral details like real-time vs cached data, rate limits, or authentication requirements.

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

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

The description is appropriately brief and front-loaded with the core action. The two-line structure separates functionality from risk assessment efficiently. No sentences are wasted, though the risk level could potentially be conveyed in a single sentence with the main description.

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

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

Given the output schema exists, the description appropriately omits return value details. However, for a tool with many SSH-related siblings, it could better contextualize when to inspect sessions versus taking action. The mention of connection slots is a good domain-specific addition.

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

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

The tool has zero parameters with 100% schema description coverage (vacuously). Per scoring guidelines, this warrants a baseline score of 4. The description correctly does not invent parameters where none 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?

The description uses a specific verb ('List') with a clear resource ('active SSH sessions') and adds scope detail ('remaining connection slots'). It clearly distinguishes this from siblings like ssh_connect, run_ssh_command, and ssh_disconnect by positioning it as a passive inspection/monitoring tool.

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

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

The description implies usage through the action (listing sessions suggests monitoring or capacity checking), but provides no explicit when-to-use guidance, prerequisites, or alternatives. It does not mention, for example, to use this before ssh_connect to verify available slots.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully adds 'Risk level: low' (safety context) and specifies return values ('liveness, idle time, and uptime'), providing crucial behavioral context beyond the schema. It could be improved by mentioning whether this operation affects session state (e.g., resets idle time) or has 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?

Every sentence earns its place: the first states purpose, the second describes returns, and the third provides safety context. The description is appropriately front-loaded with the core action and contains no redundant or wasted text despite being only three lines.

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

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

For a single-parameter health check tool with an output schema (reducing the need for detailed return documentation), the description is minimally adequate. It covers risk and return semantics but leaves the critical session_id parameter undocumented. Given the tool's simplicity, this is sufficient for basic usage but not comprehensive.

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 compensate by explaining the session_id parameter. It fails to do so, providing no information about what constitutes a valid session ID, where to obtain it (likely from ssh_list_sessions), or its format. While the parameter name is somewhat self-explanatory, the lack of any documentation for the sole required parameter is 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 uses a specific verb ('Health-check') and resource ('persistent SSH session') that clearly distinguishes this from sibling tools like ssh_connect, run_ssh_command, or ssh_list_sessions. It precisely defines the tool's scope as monitoring existing sessions rather than creating or using 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 term 'Health-check' implies usage for verifying existing session status, providing implicit context for when to use it (before relying on a session). However, it lacks explicit guidance on when to prefer this over ssh_list_sessions or what to do if the health check fails.

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

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

With no annotations provided, description carries full burden and discloses critical constraints: 'Enforces path policy, blocked extensions, and size limits' and 'Risk level: medium-high (requires user confirmation).' Could improve by noting whether transfers are atomic or overwrite 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?

Six sentences with zero waste. Logical progression from purpose → constraints → conditional requirements → prerequisites → risk classification. Front-loaded with core functionality.

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 6 parameters with 0% schema coverage and existence of output schema (covering return values), the description successfully documents behavioral constraints, security policies, and parameter interdependencies. Minor gap: does not enumerate direction values (upload/download).

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?

Excellent compensation for 0% schema description coverage. Explains semantics of justification (required for downloads), local_path (source for uploads), session_id (reuse persistent connection), and implies direction values. Missing explicit description of host_id format and remote_path semantics.

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

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

Opens with specific verbs ('Upload or download') and clear resource ('file'), immediately distinguishing it from sibling command execution tools (run_ssh_command) and connection management (ssh_connect). The bidirectional nature is explicit.

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

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

Provides strong conditional guidance: 'Downloads require a justification string' and 'For uploads, provide local_path.' Explicitly references prerequisite sibling tool ssh_connect for session_id. Lacks explicit contrast with sftp_delete for deletion scenarios.

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