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

With no annotations to fall back on, the description carries full behavioral burden and handles it well. It discloses the permission requirement, the atomic replace behavior, the fact that unknown names are returned unmatched and never create tools, the confirm flag as a write gate, and the immediate public visibility of new entries without editorial review. This goes well beyond a generic tool summary.

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?

The description is compact and front-loaded, moving from the core action to permissions, then to edge-case behavior and publication consequences. Each sentence adds necessary operational detail without repeating schema fields. There is no filler or tautology.

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 write tool with no output schema, the description covers the critical invocation details: permissions, confirmation, unknown-name handling, and side effects. The main gap is that it does not describe what the preview response looks like or what a successful replace returns, which an agent might need to interpret results. Still, the description is strong enough for correct invocation in most cases.

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%, with only agent_name documented in the schema. The description compensates by clarifying confirm semantics ('confirm=true is required to write') and the items behavior ('Unknown names are returned unmatched and never create tools'). It does not expand on item subfields like source or role, but the distinction between preview and write plus the treatment of unknown entries gives agents meaningful behavioral grounding.

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 opens with a specific verb-resource pair, 'Preview or atomically replace the token owner's aicoolies stack,' which clearly states both the action and the subject. The two modes (preview vs. replace) are distinct and differentiate it from the read/catalog sibling tools. There is no ambiguity about what this tool does.

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?

Clear context is provided: the tool manages the token owner's stack, requires stack:write permission, and requires confirm=true for writes. It implies when to use it (whenever the owner's stack needs previewing or replacing) and sets a firm precondition for the write path. It does not explicitly name alternatives or exclusions, but no sibling tool appears to be a direct substitute.

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