Skip to main content
Glama

Stat Plot Paired

stat_plot_paired

Plot paired data with one line per participant to reveal individual changes across within-subjects conditions and expose opposing responses hidden by mean-only bar charts.

Instructions

Paired-data plot — one line per participant across conditions.

WHEN TO USE: reporting any within-subjects comparison. It shows the participant-level change that the test actually analyses.

WHEN NOT TO USE: for independent groups — a boxplot or raincloud plot is appropriate there.

A bar chart of means hides participants moving in opposite directions, which is exactly the pattern that makes a mean difference misleading.

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": {
      "name": "<name>",
      "dv": "<dv>",
      "within": "<within>",
      "subject": "<subject>"
    },
    "name": "stat_plot_paired"
  }
}

Input Schema

NameRequiredDescriptionDefault
dvYes
nameYes
withinYes
boxplotNo
subjectYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full behavioral burden. It discloses what the plot shows and why, but says nothing about whether it renders inline, returns an object, saves a file, or has any side effects. Since an output schema exists, return-value detail is not required, but the operational behavior of a plotting tool remains partly unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded definition followed by clearly labelled WHEN TO USE / WHEN NOT TO USE blocks, which is easy to scan. The final sentence on why mean bars mislead is persuasive framing rather than invocation guidance, so it is slightly beyond what an agent strictly needs.

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

Completeness3/5

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

Purpose and selection guidance are complete, and the existing output schema covers return shape. However, a five-parameter tool with zero schema descriptions and no annotations should at minimum map each parameter to its role — an agent can call this correctly in intent but not confidently in arguments.

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

Parameters2/5

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

Schema description coverage is 0% across five parameters (name, dv, within, subject, boxplot), yet the description never explains any of them. The 'boxplot' boolean defaulting to true is especially opaque — presumably an overlay toggle, but the agent must guess, and 'within'/'dv'/'subject' are assumed to be column-name strings with no confirmation.

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 visualization and its structure: 'Paired-data plot — one line per participant across conditions.' This immediately identifies the resource (within-subjects data) and the rendering form, which distinguishes it from sibling plots like stat_plot_rm_corr or stat_plot_blandaltman.

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 WHEN TO USE ('reporting any within-subjects comparison') and WHEN NOT TO USE ('for independent groups — a boxplot or raincloud plot is appropriate there'). It even explains the failure mode of the alternative (bar chart of means hides opposing movement), leaving nothing to inference.

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