record_outcome

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

Goes well beyond the annotations by disclosing dedup semantics ('repeated calls for the same session/outcome are deduped'), the downstream effect on future tasks via lessons, and the conditional auth requirement for agents with registered keys. The dedup note sits slightly in tension with idempotentHint=false, but the scope is narrower (same session AND same outcome) so it reads as refinement rather than contradiction.

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?

Five sentences, front-loaded with the core action and trigger, then escalating to consequences, dedup, and auth. Every sentence carries distinct information, though the auth sentence could arguably be folded into a prerequisite note rather than trailing the description.

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?

With 11 parameters, no output schema, and permissive annotations, the description does the important work: it explains the write's downstream consequences, the dedup behavior, and the conditional auth requirement. It leaves return-value shape unexplained, but for a fire-and-record tool that is a minor 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 100%, so all 11 parameters are already documented, which sets the baseline at 3. The description adds real semantics for status enumeration and for how cause feeds lesson generation, but it says nothing about task_type, skill_id, namespace, or agent_id beyond what the schema already provides.

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 ('Record the outcome of a task you just executed') plus the memory subsystem (episodic memory), which separates it from add_evidence and infer_outcome. It does not explicitly name a sibling to contrast with, so the differentiation is implicit rather than stated.

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?

'Call this after finishing a task so past successes and failures can inform future sessions' gives a clear trigger point in the workflow. It stops short of saying when NOT to use it or naming infer_outcome/add_evidence as alternatives for related cases.

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