Shoot Plan

What changed between two versions of a plan

shoot_plan_diff

Read-only

Says what changed between two versions of a plan, so that you can catch up from a few lines instead of reading both. It compares by id, not by position, so reordering changes nothing: it lists what was added, what was removed, what changed (with the old and new values), and an id that has gone while another has appeared with the same content, which may be a rename: only a person can say. With the check results for both versions it also says which findings are new, which are resolved and which are unchanged. Input: old and new, two dpl.plan/1 objects; optionally old_findings and new_findings, the dpl.findings/1 documents shoot_plan_check returned for each: send both or neither. Output: dpl.diff/1. A plan that does not validate is refused with its diagnostics. Both plans are in one request, so the size limit is for the two together. No AI model runs. We don't keep the plan. We log a one-way fingerprint (hash) of it, its size, the tool, the type of client, the result and the time taken. Needs an agent key from a Shoot Plan account. Free, and it does not count toward the account's 3 free projects a month. Plans up to 8 MB and 120 calls a minute (5,000 a day).

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": {
      "old": "<old>",
      "new": "<new>"
    },
    "name": "shoot_plan_diff"
  }
}

Input Schema

Name	Required	Description
`new`	Yes	The later version of the plan: a dpl.plan/1 JSON object.
`old`	Yes	The earlier version of the plan: a dpl.plan/1 JSON object.
`new_findings`	No	Optional: the dpl.findings/1 document shoot_plan_check returned for the new plan. Send it together with old_findings.
`old_findings`	No	Optional: the dpl.findings/1 document shoot_plan_check returned for the old plan. Send it together with new_findings.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 26, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With readOnlyHint and openWorldHint already declared, the description adds substantial behavioral context: id-based comparison, rename detection limits, paired findings input, dpl.diff/1 output, validation refusal with diagnostics, combined size limit, no AI model, no plan retention, hash logging, authentication requirements, and rate limits. This far exceeds what the annotations provide and does not contradict them.

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?

The description is front-loaded with purpose and comparison behavior, and most sentences add useful operational context. It is longer than typical because the tool has many relevant constraints, but it remains a dense single paragraph without filler.

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 complex diff tool with an output schema, the description covers input format, paired optional findings, output type, validation failure behavior, size limits, authentication, retention, logging, and rate limits. An agent has enough information to call the tool correctly and understand the main edge cases.

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 the schema already documents each parameter, giving a baseline of 3. The description adds meaningful semantics beyond the schema by explaining that old and new are dpl.plan/1 objects, that findings come from shoot_plan_check, and that old_findings and new_findings must be sent together or not at all.

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: it says what changed between two versions of a plan. It also defines the comparison model by id rather than position and names the concrete outputs (added, removed, changed, possible renames), which clearly distinguishes it from sibling tools like shoot_plan_get or shoot_plan_check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear use case: catch up from a few lines instead of reading both plans. It also explains how to include findings from shoot_plan_check, but it does not explicitly contrast this tool with alternatives such as shoot_plan_get or shoot_plan_revision_preview.

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

All Shoot Plan 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?