Skip to main content
Glama

record_plan_rationale

Record the coach-voice explanation of the AI Coach run you are performing for this client — what you looked at, what you changed and why, and the numbers behind it. This is exactly what the client reads on their 'Why this changed' screen, so write it like a human coach speaking to them: plain language, their real figures, no tool names, no mention of steps or systems. Call this once, after you have created or adjusted their plans.

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": {
      "clientId": "<clientId>",
      "headline": "<headline>"
    },
    "name": "record_plan_rationale"
  }
}

Input Schema

NameRequiredDescriptionDefault
mathNoCalculations behind the plan (TDEE, macro targets, deficits) so the client sees it was worked out, not guessed.
inputsNoThe real figures you based the decision on (check-ins, recovery, compliance, measurements).
changesNoEach concrete change and its reason, e.g. what: "Squats 5x5 to 3x5", why: "Sleep dropped and resting HR climbed."
clientIdYes
headlineYesOne sentence on the intent, e.g. "Eased off lower body this week so you actually recover."

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • removedInput schema / properties / math / items / $ref
      Removed value: -"#/properties/inputs/items"
    • addedInput schema / properties / math / items / additionalProperties
      Added value: +false
    • addedInput schema / properties / math / items / properties
      Added value: +{
      +  "label": {
      +    "$ref": "#/properties/inputs/items/properties/label"
      +  },
      +  "note": {
      +    "$ref": "#/properties/inputs/items/properties/note"
      +  },
      +  "value": {
      +    "$ref": "#/properties/inputs/items/properties/value"
      +  }
      +}
    • addedInput schema / properties / math / items / required
      Added value: +[
      +  "label",
      +  "value"
      +]
    • addedInput schema / properties / math / items / type
      Added value: +"object"
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations declare a non-destructive write with openWorldHint=false, and the description adds the crucial context that the payload is read verbatim by the client on a 'Why this changed' screen, imposing tone and content constraints (no tool names, no mention of steps or systems). It does not state what happens on a duplicate call or whether a written rationale can be amended, which is the remaining behavioral gap.

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?

Three sentences in a deliberate order: what to record, how it will be read and therefore how to write it, then when to call it. Every clause carries actionable information — the audience, the style bans, and the timing — with no restatement of the tool name or filler.

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

Completeness4/5

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

For a five-parameter write tool with strong schema coverage and no output schema, the description supplies the missing piece an agent cannot infer: the client-facing audience and the resulting writing constraints. It is nearly complete, lacking only guidance on repeated calls or corrections to an already-recorded rationale.

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 description coverage is 80%, so the schema already documents headline, inputs, math, and changes. The description restates that grouping in narrative form ("what you looked at, what you changed and why, and the numbers behind it") and adds register guidance, but contributes no new field-level semantics or formatting constraints beyond the schema.

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 (record) and a specific artifact (the coach-voice explanation of the AI Coach run for this client), and clarifies exactly what content belongs in it — what was looked at, what changed, and the numbers. An agent knows precisely what this tool produces and that it is client-visible prose, not structured data mutation.

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?

Explicit sequencing and cardinality: "Call this once, after you have created or adjusted their plans." This tells the agent both the trigger condition and the call count, which is the main failure mode for a rationale-capture tool. No conflicting alternative is named among siblings because none performs this function.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.