Planner (proof-of-done)

goal-request-upload

PREFERRED path to attach a LARGE binary evidence file (screenshot, log dump, PDF, session transcript — anything > ~1 KB) to an acceptance criterion. Returns a one-time {uploadUrl, expiresAt} scoped to this criterion. Then STREAM the raw file to it with a single PUT — no base64, no token:

curl -sS --fail --upload-file "/abs/path/to/file.png" ""

Optionally pass the hex SHA-256 of the file so the server fast-fails on any in-flight corruption: curl -sS --fail -H "X-Content-Sha256: " --upload-file "/abs/path/to/file.png" ""

The PUT response is the same evidence JSON that goal-attach-evidence returns (evidence id, serverSha256, judge verdict, criterion evidenceCount). A non-2xx PUT means the upload was rejected (expired/already-used/wrong-criterion/hash-mismatch) and NO evidence was created — request a fresh URL and retry.

Use this instead of goal-attach-evidence for any non-trivial file. Use goal-add-evidence-text only for byte-less context (external URLs, manual repro notes) — it does NOT cover an AC.

GOAL ATTACHMENTS (description illustrations, NOT evidence): pass goalId INSTEAD of criterionId. The PUT then creates a goal attachment and returns {attachment.url, attachment.markdown} — paste markdown into the goal description and the web UI renders images inline. Such a file is not bound to any AC and never counts toward closing the goal.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	No	Optional evidence kind override. Only accepted value is `session_history` (goal-level transcript artifact; does NOT cover an AC).
`goalId`	No	UUID of a goal — issues a ticket for a DESCRIPTION ATTACHMENT (not evidence); mutually exclusive with criterionId
`caption`	No	Optional human-readable description, stored on the evidence
`createdBy`	No	Identifier of the uploading agent
`criterionId`	No	UUID acceptance criterion the file will be evidence for (omit when goalId is given)

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedAug 22, 2026

addedInput schema / properties / criterionId / default
```
Added value: +null
```

changedInput schema / properties / criterionId / description

Previous value: -"UUID acceptance criterion the file will be evidence for"New value: +"UUID acceptance criterion the file will be evidence for (omit when goalId is given)"

addedInput schema / properties / goalId

Added value: +{
+  "default": null,
+  "description": "UUID of a goal — issues a ticket for a DESCRIPTION ATTACHMENT (not evidence); mutually exclusive with criterionId",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "criterionId"
-]
```

AddedJun 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description reveals critical behavioral details beyond the readOnly/idempotent annotations: one-time uploadUrl, expiry, raw PUT streaming without base64/token, optional SHA-256 for corruption detection, non-2xx rejection semantics, and that no evidence is created on failure. It also explains the goal-attachment branch and its markdown return value.

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?

The description is long but information-dense, with the primary use case front-loaded, followed by concrete curl examples, failure semantics, and alternative-tool routing. Each paragraph earns its place and the structure is easy to scan.

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?

Given the tool's real complexity and no output schema, the description is remarkably complete: it covers the request response, the PUT protocol, the optional hash, the response shape, failure handling, and the goal-attachment variant. An agent has enough to call it correctly without additional inference.

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 100%, so the schema already documents all parameters. The description reinforces the goalId/criterionId mutual exclusivity and kind's accepted value, but it mostly repeats schema information rather than adding substantially new parameter-level meaning.

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?

The description states a specific verb and resource: 'PREFERRED path to attach a LARGE binary evidence file ... to an acceptance criterion.' It clearly delimits the tool's job from goal-attach-evidence and goal-add-evidence-text, so an agent can tell them apart immediately.

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?

Usage guidance is explicit: 'Use this instead of goal-attach-evidence for any non-trivial file' and 'Use goal-add-evidence-text only for byte-less context' with the note that it does not cover an AC. It also explains when to pass goalId instead of criterionId, giving clear routing rules.

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) tools Inspect

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

Need Help?