run_with_credential

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

Goes well beyond the annotations: it names the injected variable scheme (KM_NAME/KM_USERNAME/KM_SECRET, KM_<FIELD>, KM_URL, KM_BASIC_AUTH), per-type extras (aws, database, ssh_key with a temp 0600 file that is shredded afterward), secret scrubbing including base64/url/hex encodings, and {{km.*}} placeholder behavior. This is exactly the behavioral context annotations cannot carry, and nothing contradicts readOnlyHint=false, destructiveHint=false, openWorldHint=true.

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?

Dense and front-loaded: the core mechanism and scrubbing guarantee come first, then the variable conventions and an example. The type-extras list is long but each entry carries information an agent needs to build the command correctly.

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

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

For a high-complexity tool with no output schema and 0% schema coverage, the description supplies most of what's needed: invocation form, secret handling, encoding scrubbing, and per-type env layout. Gaps remain around timeout/cwd semantics and the meaning of ref and purpose, which are neither in the schema nor the description.

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% for 7 params, so the description must compensate. It explains env (mapping and template syntax like {{km.username}}:{{km.password}}) and stdin placeholders well, but says nothing about ref, command, cwd, timeout, or purpose, leaving a substantial share of 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?

States a specific verb+resource ('Run a bash command with the credential injected as environment variables') and a distinguishing property ('stdout/stderr are scrubbed of the secret'). An agent can immediately tell this apart from sibling tools like http_request or get_credential.

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

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

Usage is implied by the mechanism (shell out with injected secrets), but the description never says when to prefer this over siblings like http_request or get_totp, nor lists prerequisites such as which credential refs are valid. It gives a concrete example but no when/when-not routing.

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