submit_attempt

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

Annotations already establish that this is a non-read-only, non-idempotent, closed-world mutation, so the description correctly focuses on consequences: it names the exact state transition (task moves to review), the audit-finding append behavior, and a specific failure mode (retry_cap_exceeded at the plan's retry cap). That retry-cap disclosure is real value beyond the annotations. Minor gap: it does not say what happens to an existing claim or whether the submission itself can be retried after a cap error.

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 sentences, front-loaded with the verb and payload, then branching behavior, then the failure condition — a sensible order with no filler. The payload enumeration is long but each item is distinct information rather than padding.

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 important things an agent needs: what to send, what state change results, and one named error condition. The remaining gap is the claim lifecycle relationship (how ClaimToken is acquired and whether it is consumed), which matters given the retry-cap semantics but is absent.

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%, so the description must carry parameter meaning, and it partially does by enumerating the logical contents of the nested Attempt object (files changed, approach, side effects, build command, test scenario, diff reference). However, it never names the actual keys or the structure of that nested object, and it says nothing about ClaimToken (the sole required parameter) or as_agent, leaving the agent to guess how the claim token is obtained and what as_agent changes about identity.

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 immediately enumerates the payload it carries (files changed, approach summary, side effects, build command, test scenario, diff reference). It also distinguishes the two distinct effects by task type: dev-plan tasks transition to review, audit findings record into the finding's attempt chain, so an agent can tell it apart from submit_findings or submit_attempt_verdict.

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?

The description gives clear triggering context: you call it when handing off completed work on a dev-plan task or when recording a fix attempt against an audit finding, and it names the resulting state transition. It does not, however, contrast with the adjacent siblings submit_attempt_verdict or submit_review_decision, so the agent must infer that this is the pre-review submission rather than the verdict step.

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