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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the 64KB size cap, the minimum 3 public / 5 hidden cases, the freeze-on-open semantics, idempotent-repeat behavior (identical repeat succeeds, changes return 409), the needs_fixtures waiting state, the endpoint delivery of hidden inputs, and the 403/pledge_url edge case. Gaps remain: no permission model beyond 'the key that asked,' no statement of reversibility after freeze, and no description of the response body.

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 front-loads the key behavior ('The key that asked for a pot attaches...') which is good, but it then bundles four unrelated concerns—lifecycle, limits, idempotency, and the pledge fallback—into a dense run-on. Every sentence carries information, but the structure makes the primary operation hard to extract quickly.

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 10-parameter mutation tool with no annotations, no output schema, and 20% schema coverage, the description needs to do more. It covers lifecycle and validation constraints well but omits what happens on success (what the pot returns or exposes), parameter semantics for half the schema, and any authentication requirement beyond the implicit 'key that asked.' Adequate but with clear gaps.

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 20% across 10 parameters, so the description must compensate. It covers delivery limits (64KB, min case counts) and the case shapes, which partially maps to public_cases/hidden_cases constraints. But it says nothing about pass_score, key_column, input_schema/output_schema, or the required agent_key/bounty_id semantics beyond context, leaving the majority of parameters undocumented.

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 states that a key attaches public/hidden cases and a rubric to 'open' a pot contract, but it never cleanly names the operation the way the title does ('Attach a pot contract'). The phrase 'attaches its public and hidden cases and a scoring rubric to open it without paying' is specific about resource and fields, yet the core verb is tangled with lifecycle narration. It's distinguishable from siblings like bounty_pledge, but only after reading several sentences.

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?

It gives a real selection condition: 'The key that asked for a pot' may open it without paying, and explicitly names the alternative path (bounty_pledge with contract) for a pot no key asked for, including the 403/pledge_url outcome. That is better than implied usage, though it never states when this tool should *not* be called or what happens if the wrong key tries.

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