submit_attempt

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

With no annotations, the description carries the burden well: it discloses the state transition (task to review), the attempt-chain side effect on findings, and the retry_cap_exceeded error condition tied to the plan's retry cap. It doesn't mention ClaimToken authorization requirements, but the mutation behavior is otherwise well communicated.

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 tight sentences, front-loaded with the core action and payload, followed by the branching behavior and error case. The field enumeration is slightly listy but every element earns its place.

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 mutation tool with a nested Attempt object, 0% schema coverage, and no output schema, the description covers payload contents and error behavior but omits the required ClaimToken role and the as_agent parameter, leaving meaningful gaps an agent would need to infer.

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 0% with three parameters. The description enumerates the fields expected inside the Attempt object, which compensates somewhat, but it leaves ClaimToken (the required param) and as_agent entirely unexplained, so the gap is only partially filled.

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 (submit) and resource (attempt at the work) and enumerates the payload (files changed, approach summary, side effects, build command, test scenario, diff reference). It differentiates from the family of related submit_* siblings by clarifying that this records the developer's work attempt rather than a verdict or findings.

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 clear context for when it applies: dev-plan tasks transition to review, while audit findings append to the findings attempt chain. It stops short of explicit exclusions or naming when to prefer submit_attempt_verdict or submit_findings instead.

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