exec_with_secrets

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

With no annotations provided, the description carries the full burden and delivers richly. It discloses that it spawns a real child process with arbitrary side effects ('writes, network, exec'), that output is scrubbed against injected secrets, that both tool and exec policies gate usage, and details the return format ('Exit code: N' then STDOUT/STDERR blocks). The profile parameter description adds critical caveats (restricted is NOT a real OS sandbox, PATH not restricted).

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 substantial sentences, front-loaded with the verb+action and distinguishing features. The second sentence adds essential caveats. It's dense but every clause earns its place — the only minor deduction is that it's fairly long and the redaction/return-format details could arguably be tightened.

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 (9 params, multiple security modes, side effects, policies, output scrubbing) with no annotations and no output schema, the description is remarkably complete. It covers return format, behavioral caveats, policy constraints, and sibling differentiation entirely in text. Nothing critical is left unexplained for an agent to safely invoke this dangerous 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 100%, so the baseline is 3. The description goes beyond the schema by reinforcing the 'prefer env_generate/validate_secret' distinction and explaining the exec-policy gating on `command`. However, it does not enumerate parameter-specific semantics beyond what the schema already states (e.g., it doesn't detail the profile tradeoffs in the main body — those live only in the schema's profile description). Slightly above baseline.

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

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

The description begins with '[exec] Run a child shell command with project secrets injected as environment variables and any leaked secret values redacted from captured stdout/stderr' — a specific verb (Run), explicit resource (child shell command with secrets injected), and the defining behavioral trait (secret redaction). It clearly distinguishes from siblings like env_generate (write .env to disk), validate_secret (liveness checks), and get_secret/list_secrets (read-only access), naming alternatives directly.

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 when-to-use ('let an agent run a script that needs credentials... without ever putting plaintext values in the chat'), explicit prefer-alternatives ('prefer env_generate if you need to write a .env file to disk and validate_secret for upstream liveness checks'), and clear exclusions ('Subject to BOTH tool policy and exec policy'). This is textbook usage guidance.

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