Skip to main content
Glama

record_outcome

Record a task's success, failure, or partial outcome so past results inform future sessions; failures with a cause become lessons for similar tasks.

Instructions

Record the outcome of a task you just executed (episodic memory). Call this after finishing a task so past successes and failures can inform future sessions. Status must be 'success', 'failure', or 'partial'. Failures with a cause are reflected into lessons that get injected into similar future tasks. Repeated calls for the same session/outcome are deduped rather than creating a second episode. Use infer_outcome instead when the host supplies structured evidence rather than a transcript; use add_evidence to attach provenance to an existing memory. Returns status (recorded | duplicate), the episode id, and any distilled lesson. Requires agent auth when the agent has a registered key.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task": "<task>",
      "status": "<status>"
    },
    "name": "record_outcome"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoTags for categorization
taskYesWhat task was executed (kept verbatim for retrieval)
causeNoAttribution of the outcome, when known
statusYesOutcome status: success, failure, or partial
api_keyNoAPI key for agent authentication (required if agent has a registered key)
agent_idNoID of the agent reporting this outcomeunknown
skill_idNoID of the skill memory the agent followed, if any — attributes this outcome to the skill's success/failure statistics
namespaceNoNamespace for the episode memory (default: global)global
task_typeNoCoarse task category for lesson matching (e.g. deploy, debug, refactor)
agent_typeNoType of the agent (e.g., coding-assistant)general-assistant
session_idNoSession the task ran in, for traceability

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

Goes well beyond the annotations: it discloses the return payload (status recorded|duplicate, episode id, distilled lesson), the lesson-reflect-back side effect for failures with a cause, and the auth requirement. One nuance is left slightly at odds with the structured fields — annotations say idempotentHint=false while the text says repeated calls for the same session/outcome are deduped, which an agent may read as near-idempotent; clarifying that the dedupe key is session/outcome rather than args would remove the ambiguity.

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?

Purpose is front-loaded in the first sentence, followed by trigger, enum values, side effects, dedupe behavior, alternatives, returns and auth. Despite covering eight distinct points for an 11-parameter tool, there is no filler or restatement of the name.

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?

With no output schema and 11 parameters, the description carries the return contract itself and does so precisely. Auth preconditions, dedupe semantics, lesson side effects and sibling routing together cover everything an agent needs to call this correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns one step by explaining the causal role of 'cause' — 'Failures with a cause are reflected into lessons that get injected into similar future tasks' — which the schema only labels as 'attribution'. It repeats the status enum, which the schema already carries, and adds nothing about the other nine parameters.

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 — 'Record the outcome of a task you just executed (episodic memory)' — and immediately scopes it as post-task episodic memory. It is clearly distinguishable from infer_outcome and add_evidence by name and role, so an agent can pick it without opening the schema.

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?

Gives an explicit trigger ('Call this after finishing a task') plus explicit alternatives with the condition that selects each: infer_outcome when the host supplies structured evidence rather than a transcript, add_evidence when attaching provenance to an existing memory. Both the when and the when-not are named.

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