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

Goes well beyond the annotations: discloses that default enforcement is monitor, that replace resets settings unless secrets are omitted, that running evaluations keep their original checker/enforcement, that removing a policy or changing its checker cancels running evaluations, and that an auth account is required. The secret-handling caveat (travels through conversation; answer never echoes values) is genuinely useful behavioral context.

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-loads the create-or-replace purpose and is organized into logical paragraphs, but is dense and lengthy; the running-evaluation cancellation details, while useful, could be tightened. For a tool with this much subtle semantics the length is largely justified, and no sentence is pure 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?

For a 7-parameter, nested-object mutation tool with no output schema and an idempotent+destructive profile, the description covers the mutation semantics, defaults, secret handling, auth prerequisite, and what the response reports. Nothing an agent must know to invoke it correctly appears to be 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 100%, so the baseline is 3, but the description adds real meaning not in the schema: block requires block_at, org_name defaults to the first-joined org, omitted secrets keep stored values, and enforcement's monitor/block distinctions. This meaningfully compensates for schema-only documentation of the two enums.

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 and scope: 'Add a release policy to an organization, or replace the one with the same name.' It distinguishes itself from siblings by naming list_policies for checker discovery and implicitly contrasting with destroy_policy's removal semantics. An agent can tell exactly what this does without opening the 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?

Routes the agent to list_policies for checker names and settings, and to the `valet policies add` CLI path when a secret should not travel through the conversation. These are explicit alternatives for real sub-decisions. It stops short of a crisp when-not-to-use statement for the tool as a whole, but context is clear.

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