submit_task_proof

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

With no annotations provided, the description carries the full burden. It discloses that the tool costs $0.01 USDC, generates an immutable timestamped attestation record, and that payment_signature is optional. It also implies a cryptographic attestation side effect. However, it does not disclose failure modes, whether the operation is idempotent, what happens if the escrow is already completed, or whether the attestation is on-chain and irreversible. The cost disclosure is a positive behavioral trait, but more depth is needed for a financial transaction tool.

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 with the cost and core purpose. The parameter list is integrated efficiently. It earns its place with the cost disclosure and the attestation behavior. Minor redundancy: 'Submits and cryptographically attests proof of task completion' and 'Generates an immutable timestamped attestation record' overlap somewhat, but the structure is otherwise clean.

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 tool that costs money and creates an immutable record, the description is moderately complete. It covers the purpose, cost, and parameters. However, it lacks critical context: no output schema means the agent doesn't know what the return value is; no mention of error conditions (e.g., invalid escrow, already-submitted proof); no guidance on when payment_signature is required vs optional in practice. Given the financial and irreversible nature, this is a meaningful gap.

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 compensate. It does provide brief inline parameter descriptions: escrow_id (target escrow ID), worker_id (assigned worker ID), proof_data (raw result payload, SHA-256 hash, or verification URL), and payment_signature (optional x402 Base USDC transaction hash or developer mock key). This adds meaning beyond the bare schema titles. However, the descriptions are terse and leave ambiguity: what format should escrow_id be? What does 'developer mock key' mean? What constitutes valid proof_data? The description partially compensates but not fully.

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 clearly states the tool's purpose: submitting and cryptographically attesting proof of task completion, generating an immutable timestamped attestation record. It uses a specific verb ('submits') and resource ('proof of task completion'), and the mention of 'attestation record' distinguishes it from generic submission tools. However, it doesn't explicitly differentiate from siblings like verify_cryptographic_proof or claim_task_bounty, though the context makes it fairly clear.

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 implies usage context: it is for submitting proof of task completion, presumably after a task has been performed and before bounty release. It mentions the cost and the optional payment signature, which hints at when payment_signature is needed. However, it does not explicitly state when to use this tool versus alternatives like verify_cryptographic_proof (verification) or release_task_bounty (post-proof release), nor does it state prerequisites like having an active escrow.

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