ephemeral-buffer

Overview Schema Source Related Servers Discussions Admin

execute_and_capture

Run a shell command, capture its stdout/stderr into a searchable buffer, and get a compact JSON summary with status, duration, and token counts—avoiding prompt flooding from noisy output.

Instructions

Runs a shell command, captures stdout/stderr, indexes it, and returns a compact versioned JSON summary without flooding the prompt context with thousands of lines. The summary includes status, duration, sizes, approximate token counts, truncation, signals, and optional named metrics.

Use this for noisy tests, builds, logs, and other output that benefits from bounded capture and later search. Direct command execution is usually faster for a small, targeted inspection; use capture once output may be noisy, large, or uncertain. This is an advisory routing heuristic, not an enforced threshold. Before running, verify the command, intended repository, and working directory: an omitted cwd inherits the server process directory, and symlinks or shell expansion can target a different path than expected. This tool bounds output but does not validate command intent, path identity, or filesystem safety.

Args: command: Shell command line to execute. cwd: Optional working directory for command execution; pass an explicit validated path for repository-sensitive commands. label: Optional human-readable description/label for this capture. content_type: Content type hint - 'auto' (default, detects diff/log/text), 'diff', 'log', or 'text'. max_output_bytes: Maximum command output retained (default: configured buffer byte limit). timeout_seconds: Optional maximum runtime; timed-out commands return exit code 124.

Input Schema

TableJSON Schema

Name	Required	Default
`cwd`	No
`label`	No
`command`	Yes
`content_type`	No	auto
`timeout_seconds`	No
`max_output_bytes`	No
`structured_metrics`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.5.0Sep 19, 2026

addedInput schema / properties / structured_metrics

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Structured Metrics"
+}

First observedv0.2.0Sep 9, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full disclosure burden and succeeds: it warns that an omitted cwd inherits the server process directory, that symlinks/shell expansion can target unexpected paths, that it 'bounds output but does not validate command intent, path identity, or filesystem safety', and that timeouts return exit code 124. This is exemplary safety disclosure for a shell-execution tool.

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?

Purpose is front-loaded and every block earns its place — return contract, routing heuristic, safety warnings, then Args. It is longer than average, but the length is justified for a risky, 7-parameter shell tool; the structured_metrics omission in Args is the only structural blemish.

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 complex tool (7 params, output schema, high-risk shell execution, 17 siblings), the description covers purpose, routing, safety, return contents, and all parameters. An output schema exists so return-value details don't need duplication. The small remaining gaps are the unnamed direct-execution sibling and the unlisted structured_metrics parameter.

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 description coverage is 0%, so the description must compensate and largely does: command, cwd (with 'pass an explicit validated path' guidance), label, content_type (with its enum values listed), max_output_bytes, and timeout_seconds (with the 124 exit-code semantic) are all explained. The one gap is structured_metrics, which is only hinted at as 'optional named metrics' in the return summary and never appears in the Args list.

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?

Opens with a specific, multi-verb purpose ('Runs a shell command, captures stdout/stderr, indexes it, and returns a compact versioned JSON summary') tied to a concrete resource and a distinguishing behavior (bounded capture + indexing). The return contract (status, duration, sizes, token counts, truncation, signals) makes it unmistakable against siblings like get_execution_output or capture_text.

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 explicit when-to-use conditions ('noisy tests, builds, logs... bounded capture and later search') and an explicit when-not ('Direct command execution is usually faster for a small, targeted inspection'). Also frames it as an advisory heuristic rather than an enforced threshold, which prevents the agent from over-trusting the rule.

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