Append a Core REPORT to record the outcome of a specific task attempt, without accepting or archiving the work.
Append a Core REPORT for the explicit TASK attempt; reporting does not accept or archive work.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| result | Yes | ||
| sender | Yes | ||
| recipient | Yes | ||
| attempt_id | Yes | ||
| references | No | ||
| report_kind | No | final | |
| subject_ref | Yes | ||
| workspace_id | Yes |
Changes observed during successful MCP inspections.
v4.0.5Input schema / properties / attempt_idAdded value: +{
+ "type": "string"
+}Input schema / properties / body / descriptionRemoved value: -"Report body in Markdown."Input schema / properties / priorityRemoved value: -{
- "default": "P2",
- "description": "FCoP priority; accepts ``P0``–``P3`` and aliases.",
- "type": "string"
-}Input schema / properties / recipient / descriptionRemoved value: -"Recipient role code (typically the PM)."Input schema / properties / referencesAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / report_kindAdded value: +{
+ "default": "final",
+ "type": "string"
+}Input schema / properties / reporterRemoved value: -{
- "description": "Reporter role code (uppercase).",
- "type": "string"
-}Input schema / properties / resultAdded value: +{
+ "type": "string"
+}Input schema / properties / senderAdded value: +{
+ "type": "string"
+}Input schema / properties / statusRemoved value: -{
- "default": "done",
- "description": "``done`` / ``in_progress`` / ``blocked``.",
- "type": "string"
-}Input schema / properties / subject_refAdded value: +{
+ "type": "string"
+}Input schema / properties / task_idRemoved value: -{
- "description": "Source task ID (e.g. ``TASK-20260423-001``).",
- "type": "string"
-}Input schema / properties / workspace_idAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "task_id",
- "reporter",
- "recipient",
- "body"
-]New value: +[
+ "workspace_id",
+ "sender",
+ "recipient",
+ "subject_ref",
+ "attempt_id",
+ "body",
+ "result"
+]Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "type": "object",
- "x-fastmcp-wrap-result": true
-}New value: +nullv3.2.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it does disclose the append-only nature and that the call does not accept or archive work, which is the key safety distinction. It says nothing about prerequisites (must the attempt exist?), permissions, idempotency of repeated appends, or failure modes for a 9-parameter mutation.
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?
A single front-loaded sentence with no filler; the scope ('Append') and the key constraint (not accept/archive) come first. Its brevity is efficient, though it borders on under-specified for the parameter surface.
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?
Nine parameters, seven required, zero schema descriptions, no annotations, no output schema — this is exactly where the description needs depth, and it provides one sentence. An agent cannot tell what belongs in body versus result or what report_kind values mean.
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% across 9 parameters, so the description must compensate, yet it names no parameters. 'attempt' hints at attempt_id and 'TASK' hints at subject_ref, but body, result, sender, recipient, report_kind, references, and workspace_id are entirely unexplained.
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 and resource ('Append a Core REPORT') scoped to a TASK attempt, and distinguishes itself from state-changing siblings by saying reporting 'does not accept or archive work'. The jargon 'Core REPORT' and 'explicit TASK attempt' keep it from being fully unambiguous.
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?
Provides one useful exclusion ('does not accept or archive work'), implicitly pointing at submit_task/approve_task/archive_task as the alternatives for state change. It never positively says when to choose write_report over write_issue or write_review, so guidance remains inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.