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 at all, the description carries the full burden and does so well: "Read-only; never returns secret values" is exactly the safety statement an agent needs before calling. It also enumerates the returned fields. Gaps remain on things like whether presets are user-scoped or paginated, but nothing material is contradicted.

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 what the tool is and what it returns, then routing guidance last. The closing routing sentence is useful but is arguably sibling-tool documentation leaking into this definition; it slightly dilutes focus on a four-line 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?

A zero-parameter, read-only listing tool with an output schema needs little more than this, and the definition supplies definition, return fields, and safety posture. The redundant restatement of return fields is harmless given it also clarifies types and approval policy semantics that the raw schema may not.

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 input parameters, so the baseline applies — there is nothing for the description to disambiguate. It correctly says nothing about parameter syntax rather than padding out obvious absences.

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 immediately defines the resource in-line ("named, scoped actions you may invoke") plus the returned fields. An agent can distinguish this discovery tool from the action-executing siblings without opening any schema.

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 routes to `proxy_http` for HTTP actions and constrains `get_secret_for_env` to a last-resort environment-variable case, which is real when-to-use guidance. It never states the complementary rule ("call this first to discover which presets exist before invoking one"), so the primary usage context is only implied.

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

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

With no annotations, the description carries the full burden and does so: server-side allow-list validation before credential injection, mandatory user approval for sensitive presets that cannot be bypassed, time-boxed approval windows recorded as 'windowed' in the audit log, and universal audit logging. It also warns that response bodies are untrusted data and that presets may cap size or omit fields signaled via `notice`.

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 core action, then layered with security and trust-boundary details in a logical order. It is on the longer side and the audit-log and windowed-approval sentences could be tightened, but each conveys operationally relevant 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 an output schema exists, the description need not explain return values, yet it still flags the `notice` field for truncated responses and the untrusted nature of response data. Approval flow, validation order, and preset discovery are all covered, leaving nothing an agent needs in order 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 coverage is 100%, so the schema already documents all five parameters, making 3 the baseline. The description adds modest meaning — that preset_name must exist in list_presets and that method/path are checked against the preset's allow-list — but contributes no format or syntax detail beyond the schema.

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

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

Opens with a specific verb+resource: 'Make an HTTP request through a preset.' It immediately distinguishes the tool from siblings like db_query, ssh_exec, and sftp_transfer by framing the operation as preset-mediated HTTP with server-selected base URL and credentials.

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?

Explains the operating context clearly: the preset supplies base URL/auth, the caller supplies path/method/body/query, and preset_name must exist in list_presets (routing the agent to that sibling for discovery). It does not explicitly state when to prefer this over ssh_exec or db_query, so it stops short of full alternative routing.

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, the description carries the full burden and does so thoroughly: command whitelisting rules, character restrictions, refusal of shell metacharacters, key-based auth only, known_hosts host-key verification, approval prompts for sensitive presets, time-boxed window reuse recorded as 'windowed', and audit logging of every call. This is exactly the behavioral context an agent needs before attempting an exec.

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 action in sentence one, followed by constraint, then behavior/auth, then approval/audit details. Dense but nearly every clause carries operational value; the only mild cost is a long, unbroken block with no separation between invocation constraints and side-effect behavior.

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 mutation-capable tool with no annotations, everything an agent needs is present: invocation constraints, auth model, approval flow, audit trail, and even return values (stdout, stderr, exit_code) despite an output schema existing. Nothing material 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?

Schema coverage is 0%, so the description must compensate, and it richly constrains `command` (must match an anchored regex, single-space separated words, restricted character set, no quotes/globs/redirections). `preset_name` is only implied via references to 'the preset' and 'allowed_commands', without stating how to discover valid names (list_presets), leaving one 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 first sentence states a specific verb and resource with a precise target: 'Run a shell command on the preset's SSH host.' Against siblings like sftp_transfer, proxy_http and db_query, an agent can immediately tell this is the host-shell execution tool rather than a file transfer, HTTP proxy, or database path.

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 spells out the conditions under which a call will succeed, be refused, or trigger an approval prompt (allowed_commands regex match, sensitive presets, previously approved time-boxed windows). It does not explicitly route the agent to an alternative sibling (e.g. use sftp_transfer for files, proxy_http for HTTP), so it stops short of full when/when-not/alternative guidance.

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