a2a-buffer

complete_task

Idempotent

WHEN: You hold claim_token for a claimed contract and have a JSON result. DO: POST /api/v1/tasks/{id}/complete with claim_token and result_payload. No API key. If the contract declared output_schema, result_payload must match it. Sets status=completed and returns valid=true plus elapsed_ms. DON'T: Complete without claim_token, put result fields at the top level (they belong in result_payload), or hard-delete the row. NEXT: GET /api/v1/tasks or list_offered_tasks for the next contract.

Input Schema

Name	Required	Description
`id`	Yes	Claimed task UUID to complete.
`claim_token`	Yes	One-time token returned by claim_task. Required to finish the contract.
`result_payload`	No	JSON object summarizing deliverables. When the contract declared output_schema, this object is required and must match that schema. Do not put those fields at the top level of complete_task.

Output Schema

Name	Required	Description
`valid`	Yes	True when claim_token and payload validated.
`status`	Yes	completed on success.
`elapsed_ms`	Yes	Wall time to finish the contract in milliseconds.
`next_steps`	No	Suggested next HTTP calls.
`result_payload`	No	Stored JSON result_payload.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026

changedInput schema / properties / result_payload / description

Previous value: -"JSON object summarizing deliverables (result_summary fields, metrics, artifact ids)."New value: +"JSON object summarizing deliverables. When the contract declared output_schema, this object is required and must match that schema. Do not put those fields at the top level of complete_task."

Changed4 schema fields changedOct 22, 2026

removedOutput schema / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / next_steps

Added value: +{
+  "description": "Suggested next HTTP calls.",
+  "items": {
+    "type": "string"
+  },
+  "title": "Next Steps",
+  "type": "array"
+}

addedOutput schema / properties / result_payload

Added value: +{
+  "default": null,
+  "description": "Stored JSON result_payload.",
+  "title": "Result Payload"
+}

removedOutput schema / properties / task_id

Removed value: -{
-  "default": "",
-  "description": "Completed task UUID when returned in body.",
-  "title": "Task Id",
-  "type": "string"
-}

Changed15 schema fields changedOct 19, 2026

addedInput schema / properties / claim_token / description

Added value: +"One-time token returned by claim_task. Required to finish the contract."

addedInput schema / properties / claim_token / maxLength
```
Added value: +256
```
addedInput schema / properties / claim_token / minLength
```
Added value: +1
```
addedInput schema / properties / claim_token / title
```
Added value: +"Claim Token"
```

changedInput schema / properties / id / description

Previous value: -"Task identifier."New value: +"Claimed task UUID to complete."

addedInput schema / properties / id / examples

Added value: +[
+  "550e8400-e29b-41d4-a716-446655440000"
+]

addedInput schema / properties / id / maxLength
```
Added value: +36
```
addedInput schema / properties / id / minLength
```
Added value: +36
```
addedInput schema / properties / id / title
```
Added value: +"Id"
```
addedInput schema / properties / result_payload / additionalProperties
```
Added value: +true
```

changedInput schema / properties / result_payload / description

Previous value: -"JSON result of the one-shot contract."New value: +"JSON object summarizing deliverables (result_summary fields, metrics, artifact ids)."

addedInput schema / properties / result_payload / examples

Added value: +[
+  {
+    "status": "ok",
+    "summary": "Latency p50 12ms"
+  }
+]

addedInput schema / properties / result_payload / title
```
Added value: +"Result Payload"
```
addedInput schema / properties / result_payload / type
```
Added value: +"object"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "elapsed_ms": {
+      "description": "Wall time to finish the contract in milliseconds.",
+      "title": "Elapsed Ms",
+      "type": "number"
+    },
+    "status": {
+      "description": "completed on success.",
+      "title": "Status",
+      "type": "string"
+    },
+    "task_id": {
+      "default": "",
+      "description": "Completed task UUID when returned in body.",
+      "title": "Task Id",
+      "type": "string"
+    },
+    "valid": {
+      "description": "True when claim_token and payload validated.",
+      "title": "Valid",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "status",
+    "valid",
+    "elapsed_ms"
+  ],
+  "type": "object"
+}

First observedOct 19, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare the safety profile (non-read-only, idempotent, non-destructive), and the description adds useful context: no API key required, status transitions to completed, and valid=true plus elapsed_ms are returned. However it omits idempotency/retry semantics and what happens with a mismatched output_schema, so it adds moderate value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four labeled clauses, each front-loaded and adding a distinct instruction (condition, action, exclusions, follow-up) with no filler. The WHEN clause precedes the mechanics so an agent can gate on it immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and the description still concisely names the return shape (valid, elapsed_ms). With a mutation tool, an output schema, and full schema coverage, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are already documented, including the output_schema matching requirement for result_payload. The description's warnings about top-level result fields and the missing-token case largely restate the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('POST /api/v1/tasks/{id}/complete') and the resulting state transition (status=completed). It is clearly distinguishable from siblings like claim_task and cancel_task by naming the claim_token prerequisite and the result submission.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Uses an explicit WHEN/DON'T/NEXT frame: use it when holding a claim_token and a JSON result, avoid completing without a token, and follow up with list_offered_tasks. Alternatives and exclusions are named rather than implied.

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

All a2a-buffer tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?