guard_exec

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is already known; the description adds real context beyond them: execution inside an isolated process, sanitization in volatile RAM, tokenization of secrets/PII, and in-memory mapping for later restoration. It omits what happens on timeout, whether the sanitized output is the actual return value, and permissions/error 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?

Two dense sentences with very little waste; the core action is front-loaded after a short branding phrase ('Zero-Trust Agentic Guard'). The marketing prefix costs a few words but the remainder is information-rich and non-repetitive.

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, no-output-schema tool that runs arbitrary commands, the description explains the sanitization pipeline but not the return shape the agent receives, timeout behavior, or that 'safe local restoration' is accomplished via the reveal_text/guard_unmask_args siblings. Enough to call it, not enough to reason about the full round-trip 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 100%, so all six parameters (cwd, sector, profile, command, session_id, timeout_ms) are already documented in the schema. The description adds no parameter-level meaning beyond implying that the profile drives the tokenization step. Baseline 3 applies when the schema does the heavy lifting.

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 ('executes a shell/terminal command locally') and immediately describes the sanitization of stdout/stderr before output reaches the LLM. The resource (arbitrary shell command) implicitly separates it from narrower siblings like guard_read_file and guard_git_diff, though those siblings are never named.

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?

There is no explicit when-to-use or when-not-to-use guidance. The description never says to prefer guard_read_file or guard_git_diff for those specific operations, nor does it explain when the sanitization wrapper is warranted versus running a command unguarded. Usage is only inferable from the word 'safely'.

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