mcp_sandbox

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 that 'set' is a partial patch ('only the fields you pass change, the rest keep what the server has now or would get by default') and that changes are deferred ('applies on next connect'). These are non-obvious mutation semantics an agent could not infer from the schema. It still omits the permission/authorization requirements and what a failed or rejected grant looks like.

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?

A single dense sentence with the purpose front-loaded and the action routing following in priority order. It is long but every clause (partial-update behavior, deferred application) earns its place; only the nested parenthetical stacking costs it a point.

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?

No annotations and no output schema, and for a 9-parameter policy mutation tool the description covers actions and mutation semantics adequately. It does not say what 'view' returns or how enforcement failures surface, but the schema's enum descriptions (e.g. l2-container requires Docker) pick up part of that slack.

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 documents all nine parameters, including enum values and the [set] action prefixes. The description's only added parameter meaning is the merge semantics for omitted fields on 'set', which is useful but marginal. Baseline 3 is appropriate 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 pair (view/customize) and the exact resource (a server's sandbox capability manifest), then enumerates the four policy domains it covers (env/network/filesystem/subprocess). No sibling tool deals with sandbox grants, so the agent can route to it unambiguously.

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?

Maps each action enum value to a purpose: 'view' to inspect, 'set' to tighten or loosen grants, 'reset' to revert to defaults. This tells the agent which action to pick but gives no guidance on when this tool is preferable to adjacent tools like mcp_connect or mcp_profiles, nor any prerequisites.

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