Skip to main content
Glama

Planner (proof-of-done)

by com.monopoly-gold.planner
OverviewDiscussionsAdmin

goal-attach-evidence

PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence (screenshot, log dump, API response, export) to an AC — call it once per criterion to satisfy the close gate. The subordinate goal-add-evidence-text only adds context for proofs with NO bytes (URLs to permanent external sources, manual repro descriptions) and does NOT cover an AC. Caption is optional but strongly recommended: state what the file captures and the reproduction conditions (URL/commit/session/inputs) so a third reviewer can reproduce.

⚠ PICK THE RIGHT TRANSPORT BEFORE YOU CALL THIS TOOL ⚠ • BEST for ANY file > ~1 KB raw — and the ONLY no-token path, so use it in a claude.ai / hosted-agent session that has no raw X-Auth-Token → call the sibling MCP tool goal-request-upload with this same criterionId. It returns a one-time {uploadUrl, expiresAt}; then stream the raw bytes with a single PUT: curl -sS --fail --upload-file "/abs/path/to/file.png" "<uploadUrl>" (optionally add -H "X-Content-Sha256: " so corruption fails fast). No base64, no token — the signed ?t= ticket in the URL is the only credential, single-use, criterion-scoped. The PUT response is the same evidence JSON this tool returns. • ALTERNATIVELY, if you DO have the raw X-Auth-Token in your shell → the planner-attach.sh helper (zero-install bash, binary-safe). The MCP base64 path below is unreliable for non-trivial files: long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent. Measured 2026-05-20 on prod: a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch); a 2 KB payload arrived with stray whitespace (failed base64_decode). The server itself accepts up to 25 MiB raw — the bottleneck is the agent-side serialisation of contentBase64, NOT the server.

planner-attach.sh COPY-PASTE RECIPE (replace 3 placeholders, run in your shell): curl -sS https://planner.monopoly-gold.com/api/cli/planner-attach.sh
| PLANNER_TOKEN="" bash -s --
--criterion-id ""
--file "/abs/path/to/file.png"
--caption "what is captured and the repro conditions"
--created-by ""

Where to get each value:

  • PLANNER_TOKEN: the very same token that is already in your MCP config under the X-Auth-Token header for the planner server. NOT a separate credential.

  • CRITERION_UUID: the AC id you got from goal-get / goal-list. Same UUID you would pass to this MCP tool.

  • file path: absolute path on YOUR (agent) machine — the script reads it locally and streams multipart. The planner server never sees your filesystem.

The helper computes SHA-256 itself and ships it as contentSha256, so any in-flight corruption fails fast with HTTP 400 instead of poisoning the evidence row. Output on stdout is the same JSON shape this MCP tool returns; non-zero exit means HTTP ≥ 400 (stderr explains).

Without curl/bash? Fall back to raw multipart: POST https://planner.monopoly-gold.com/api/criteria//evidence/file, header X-Auth-Token, form fields file=@..., contentSha256=..., caption, createdBy. • File ≤ ~1 KB raw → this MCP tool is fine. ALWAYS pass contentSha256 (hex SHA-256 of raw bytes BEFORE base64). Without it, a silently truncated PNG looks valid to the MIME sniffer; the server cannot distinguish a truncated 4 KB PNG from a valid 1 KB one and the vision judge burns ~30s on broken bytes. With the hash, the server fast-fails with error=file_hash_mismatch and points back here at the multipart endpoint.

Validates MIME whitelist (png/jpeg/webp/gif/mp4/pdf/txt/json/zip), per-file size cap (ATTACHMENTS_MAX_FILE_BYTES, default 25 MiB), per-project attachments quota. Returns evidence record + file URL + serverSha256.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindNoOptional evidence kind override. The only accepted value is `session_history` — marks this attachment as the goal-level «full Claude session transcript» artifact required by the close gate (I4-session-history). Such evidence does NOT cover any AC and is NOT sent to the evidence judge. Omit for normal per-AC proof (kind is derived from MIME). NOTE: transcripts are usually > 1 KB → use goal-request-upload (pass kind=session_history) or the multipart helper, not this base64 path.
captionNoOptional human-readable description, stored in evidence.payload
filenameYesOriginal filename (used to derive MIME). Path components are stripped.
mimeTypeNoMIME type — if omitted, derived from filename extension; must be in whitelist
createdByNoIdentifier of the uploading agent
criterionIdYesUUID acceptance criterion the file will be evidence for
contentBase64YesFile payload, base64-encoded (RFC 4648 §4 standard alphabet, padding optional)
contentSha256NoHex-encoded SHA-256 of the raw bytes (before base64). When provided, the server recomputes the hash on the decoded payload and rejects with error=file_hash_mismatch if they diverge — primary defence against MCP base64 truncation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.7/5.0
Behavior5/5

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

With only readOnlyHint=false and idempotentHint=false (no safety coverage), the description carries full burden and exceeds it: it discloses the known agent-side failure mode with measured data ('a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch)'), the validation rules (MIME whitelist, 25 MiB cap, per-project quota), the fast-fail behavior on hash mismatch, and the return shape (evidence record + file URL + serverSha256). It also clarifies the kind=session_history semantic (does NOT cover an AC, not sent to judge). This is substantial disclosure far beyond the annotations.

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

Conciseness3/5

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

Well front-loaded (purpose → routing warning → recipes) and hierarchical, but overly verbose: the planner-attach.sh copy-paste recipe, curl invocation details, and multipart POST fallback occupy several paragraphs. The core routing decision could be compressed, and some transport/recipe detail could be trimmed without losing the decision-critical guidance. Every section earns some place, but the length is bloated.

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?

For a high-complexity tool (8 params, transport selection, validation rules, documented failure modes, no output schema), the description is remarkably complete: it states return values ('Returns evidence record + file URL + serverSha256', 'Output on stdout is the same JSON shape this MCP tool returns'), covers the session_history special case, gives security context (no token needed on the upload path, signed ticket is single-use), and explains when each transport is appropriate. Nothing an agent needs to call it correctly is missing.

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 baseline is 3. The description adds meaningful semantics beyond schema on the riskiest params: contentBase64 is flagged as unreliable ('long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent'), contentSha256 is explained as the integrity defense that makes the server 'fast-fail with error=file_hash_mismatch', and criterionId is traced to its source ('the AC id you got from goal-get / goal-list'). This enriches the schema without duplicating it.

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 precise statement of verb, resource, and scope: 'PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence... to an AC — call it once per criterion to satisfy the close gate.' It differentiates explicitly from goal-add-evidence-text (does NOT cover an AC) and implies distinction from goal-attach-assumption-evidence and goal-attach-file. An agent can tell exactly what this tool does and what it is not.

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?

Provides explicit, condition-based routing: 'File ≤ ~1 KB raw → this MCP tool is fine' vs 'BEST for ANY file > ~1 KB raw... call the sibling MCP tool goal-request-upload'. It names goal-request-upload as the alternative, states when NOT to use this tool (non-trivial files due to agent-side base64 truncation), and gives a multipart fallback. Nothing is left to inference.

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

All Planner (proof-of-done) toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources