do_outcome

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

With no annotations, the description carries the full disclosure burden. It implies a write ("Attach", "records") and hints at two distinct modes (decision outcome vs plan check), but says nothing about idempotency, overwrite behavior if an outcome already exists, required permissions, or side effects. The mutual exclusivity of ok and correct_choice is the only real behavioral fact conveyed.

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 text is short with no filler, but the structure is fragmentary: a bare imperative, then a bracketed field list, then two trailing clauses. The plan_id mode is appended after the input enumeration rather than integrated, forcing the reader to reconcile it with the list above.

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?

An output schema exists, so return values need not be described, which relieves some burden. But for a mutation tool with zero annotations and a fully undocumented nested payload object, the description should explain the meaning of the flags and the consequences of recording an outcome; it only partially does so.

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 coverage is 0% and the only schema property is an untyped `payload` object, so the description does meaningful work by naming decision_id (required), ok, correct_choice, and note. However it never explains what ok or correct_choice actually mean or their types, and it introduces plan_id in the second sentence without listing it among the inputs — creating ambiguity about whether it is a payload field or a top-level argument.

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?

"Attach the real outcome" states a verb and object but is cryptic in isolation — it does not say outcome of what (a decision, per the decision_id field) or how it differs from siblings like do_record, do_decide, or dm_outcome. The parenthetical field list and the plan_id clause give a partial picture of the resource, but an agent cannot cleanly separate this tool from its many do_*/dm_* neighbours.

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 input-shape constraints ("Either ok or correct_choice may be given") and one conditional mode ("With plan_id + ok, records a user check result for a plan"), but these are preconditions, not when-to-use guidance. It never says when to call do_outcome versus do_record, do_decide, or do_report, and offers no exclusions or ordering advice.

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