pad_write

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description reinforces this by stating the operation 'fully overwrites' and that overwrite requires passing expected_revision (optimistic concurrency). It also discloses that pad names are unique per project, implying a duplicate-name failure. It does not say what happens if expected_revision is stale, which would round this out.

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?

Three short sentences, front-loaded with the create/overwrite distinction, followed by the uniqueness constraint and the alternative-tool routing. No filler; each sentence changes how the agent would call it.

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?

An output schema exists and annotations cover the safety profile, so return values and destructiveness need not be restated. The description covers both modes, the concurrency contract, uniqueness, and siblings. The only material gap is behavior on revision mismatch and tag merge semantics.

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 only 33% (pad_id and project_id documented in-schema), so the description must compensate for name, tags, content, expected_revision. It adds meaning for pad_id+'expected_revision' and for name uniqueness, but says nothing about tags semantics (replace vs merge) or content format. Baseline 3 given partial coverage and partial compensation.

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 distinguishes two modes: create a new pad, or 'fully overwrite one by passing pad_id plus expected_revision'. It also names the sibling pad_append/pad_edit as the lighter-weight alternatives, so an agent can separate this from neighboring pad tools without reading schemas.

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?

Explicitly routes the agent: 'Prefer pad_append/pad_edit for targeted changes', giving the condition that selects the alternative. It lacks an explicit when-not for this tool (e.g. don't use to add a single line), but the guidance is clear and actionable.

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