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

With no annotations, the description carries the full burden and does so: it discloses that the SQL is fixed at preset definition time, that an approval prompt fires per policy, that a previously approved time-boxed window bypasses the prompt and is logged as 'windowed', and that results come back as JSON rows. These are non-obvious side effects an agent must know before calling.

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 critical constraint (named query only, no arbitrary SQL) is front-loaded and the return format follows. The closing sentence on the pre-approved window is longer than needed but conveys a real behavioral difference rather than 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?

Return values are covered by the output schema and the approval/audit behavior is explained in prose, so the main gaps are covered. The one omission is a definition of preset_name and where presets come from, which matters for a three-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 coverage is only 67%, and the description compensates by explaining that query_name must match a preset-declared name and that params are positional with types matching the named query's param_types. The remaining undocumented parameter, preset_name, is left implicit — the agent can infer it but it is never defined.

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

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

States a specific verb and resource ('Run a NAMED QUERY against a database preset') and immediately bounds the scope with 'you cannot send arbitrary SQL'. This distinguishes it from a generic SQL tool and from siblings like list_presets or proxy_http without needing their schemas.

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?

Clearly establishes the precondition that query_name must match one declared in the preset, and explains the approval flow that governs invocation. It stops short of explicitly routing the agent to a sibling (e.g. list_presets to discover query names) or stating when another tool such as proxy_http would be preferred.

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 behavioral burden and does so well: it discloses that approval is ALWAYS required regardless of preset policy, warns that the returned value must not be quoted into the reasoning trace, and routes agents toward the safer alternative. These are material security and approval behaviors beyond what the schema provides.

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

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

The definition is front-loaded with what the tool does, then approval behavior, then alternative-tool guidance, then the secret-handling warning. Every sentence earns its place, and there is no redundant restatement.

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

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

An output schema exists, so the description need not explain return values. Given the tool's sensitivity and single required parameter, the description is complete enough: it covers purpose, approval behavior, preferred alternative, concrete use case, and handling constraints.

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

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

The schema already documents the single `name` parameter at 100% coverage, so the baseline is 3. The description reinforces that the name identifies the bound secret, but adds no further syntax or format details 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 states a specific verb and resource: reveal the raw secret value bound to a name. It also distinguishes this tool from the preferred sibling `proxy_http`, so an agent can tell exactly what this tool does and when it is the wrong choice.

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 gives explicit routing guidance: prefer `proxy_http`, and only use this tool when a child process must read the secret from an environment variable, with a concrete `terraform apply` example. This is exactly the when-to-use versus when-not-to-use context an agent needs.

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 present, the description carries the full burden and does useful work: 'Read-only; never returns secret values' pre-answers the two things an agent most needs to know about a credential-adjacent listing tool. It also discloses the exact return shape including enum values (http|ssh, auto|prompt|deny). It stops short of stating auth requirements, ordering, or pagination behavior for large preset sets.

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

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

Front-loaded with the verb and resource in the first clause, then the return fields, then the safety note, then routing. Four tight clauses with no filler. The final sentence about get_secret_for_env earns its place as routing guidance but is the weakest link — it is about a sibling's usage more than this tool's.

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

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

A zero-parameter, read-only discovery tool with an output schema and no annotations: everything an agent needs is present. Purpose, return fields, safety profile, and sibling routing are all covered, and the output schema handles the return structure so no further detail is owed.

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

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

Zero parameters, so there is no semantic gap for the description to fill and the baseline of 4 applies. The description correctly spends no words on arguments and instead explains the return shape, which is the only remaining surface for a parameterless tool.

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

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

States a specific verb and resource ('List available mcp-warden presets') and goes further by defining what a preset is: 'named, scoped actions you may invoke.' That definition plus the enumerated return fields (name, description, type, approval policy) makes it unmistakably distinct from the execution siblings like proxy_http and ssh_exec.

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 routes the agent away from this tool when action is needed: 'Use `proxy_http` for HTTP actions and `get_secret_for_env` only as a last resort.' That is explicit guidance on alternatives. What it never states outright is the inverse trigger — 'call this first to discover which preset to invoke' — so the when-to-use side is inferred from the word 'List' rather than declared.

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 the full burden and discloses important behavior: server-side allow-list validation before credential injection, approval prompts for sensitive presets, non-bypassable approval, time-boxed approval windows, and audit logging. This is unusually complete for a security-sensitive proxy 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?

The description is front-loaded with the core action and then adds relevant security and audit details. It is generally efficient, though the audit-log point is slightly repeated across sentences.

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 no annotations, five parameters, and an output schema; the description covers purpose, validation, authentication flow, approval behavior, and audit logging. An agent has enough context to invoke it correctly without needing 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?

Schema description coverage is 100%, so the schema already explains all five parameters. The description reinforces the preset/path/method/body/query roles but does not add syntax or semantic detail beyond what the input schema provides.

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

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

States a specific verb and resource: making an HTTP request through a preset. It also explains the preset's role and the caller-supplied fields, which clearly distinguishes it from sibling tools like ssh_exec, sftp_transfer, or db_query.

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 operational context: the preset supplies base URL and authentication, while the caller supplies path, method, and optional body/query. It does not explicitly compare this tool against alternatives or state when not to use it, so it falls short of a 5.

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 the full burden and does well: it discloses always-on key-based auth, host-key verification, path sandboxing, and the approval/audit behavior where a pre-approved window lets the call proceed without a prompt and be logged as 'windowed'. It omits what happens to an existing local file (overwrite/abort) and any size limits, which keeps it from a 5.

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

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

Four sentences, front-loaded with the core action, then constraints, then auth, then approval behavior — a sensible information order. The direction sentence duplicates the schema's own enum wording, which is mild 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?

An output schema exists, so return values need not be explained, and the description covers the security-relevant behavior an agent needs before calling: auth model, path sandbox, and the no-prompt audit-window case. Destination overwrite semantics and error behavior on path rejection are the main gaps.

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

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

Schema coverage is only 25% (only direction is documented in the schema, and the description merely restates it), so the description must compensate — and it does, supplying the constraint semantics for remote (sftp_allowed_paths prefixes) and local ($HOME or /tmp) that the schema lacks entirely. Only preset_name is left implicit.

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 a specific verb and resource: 'Transfer a file between the preset's SSH host and the local machine.' An agent immediately knows this is file movement, distinct from ssh_exec (command execution) or db_query. It stops short of naming a sibling to contrast with explicitly, so it stays at 4.

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 concrete hard constraints on when a call is valid: direction must be get or put, remote must match the preset's sftp_allowed_paths prefixes, local must be under $HOME or /tmp. It never says when to prefer this over ssh_exec or what to do if a path is rejected, so usage context is implied 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses key-based auth only, known_hosts verification, approval prompts for sensitive presets, time-boxed approval windows, and audit logging. It also specifies return fields (stdout, stderr, exit_code), making the tool's behavior very clear.

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 front-loaded with the core action and then layers constraints, return values, auth, approval, and audit behavior without wasted wording. Every sentence adds operational information an agent needs.

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

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

For a complex remote command execution tool with no annotations and 0% schema description coverage, the description is quite complete: it covers auth, host verification, approval, audit logging, command restrictions, and return values. It still lacks details such as command timeout behavior or how presets are discovered, but the core invocation context is well covered.

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 both parameters. It meaningfully defines `command` as a shell command subject to anchored `allowed_commands` regexes and establishes that `preset_name` selects the SSH host, allowed commands, and approval context, though it does not explain how to discover preset names.

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

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

The description gives a specific verb and resource: 'Run a shell command on the preset's SSH host.' It clearly distinguishes this tool from siblings such as db_query, sftp_transfer, and proxy_http by naming shell execution over SSH as the action.

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 preconditions such as the command matching `allowed_commands` regexes and key-based auth, which implies when the tool can run. However, it does not explicitly compare this tool with siblings like sftp_transfer or proxy_http or state when to choose an alternative.

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