Skip to main content
Glama

Planner (proof-of-done)

by com.monopoly-gold.planner
OverviewDiscussionsAdmin

goal-add-criterion

Append an acceptance criterion to a goal. The text must describe an observable check over an artifact (e.g. "GET /api/health returns 200 with {status:ok}"), not a subjective approval. Each criterion has a class: pre-merge (default — proved in CI / by attached evidence) or post-deploy (proved by an executable probe against the deployed prod instance). A post-deploy criterion MUST carry probeSpec {method, url, expect:{http_code, body:{field: expectedValue}}} — the request the runner sends and the answer it must get; without it the call is rejected with error=probe_required. Passing probeSpec alone implies probeClass=post-deploy. Set visualEvidenceSuggested=true only when adopting visualAcSuggestion from goal-create, goal-get, or the ready_for_work advisory returned by goal-update; it remains an ordinary AC. Grove mode: AC (class and probe included) can only be added while goal is in backlog, except accepting a visual advisory in ready_for_work: that starts a direct checking_ac recheck, without intermediate backlog. Other edits are frozen once started; quality linter blocks high-severity issues. Standard mode: AC editable until goal is closed, linter is advisory. Returns criterion id, position, text, probeClass, probeSpec and any quality findings.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
textYesФормулировка критерия
goalIdYesUUID цели
positionNoПозиция (default = append в конец)
probeSpecNoИсполнимая проба post-deploy критерия: {method: GET|HEAD|POST|PUT|PATCH|DELETE, url: абсолютный http(s), expect: {http_code: 200, body: {field: expectedValue, nested: {field: value}}}}. Ожидаемые значения фиксируются сейчас; единственная подстановка времени прогона — "{{deployed_revision}}" (SHA развёрнутой ревизии). Пример: {"method":"GET","url":"https://planner.monopoly-gold.com/api/healthz","expect":{"http_code":200,"body":{"status":"ok","revision":"{{deployed_revision}}"}}}
probeClassNoКласс критерия: pre-merge (default; доказывается в CI / приложенным evidence) или post-deploy (доказывается исполнимой пробой против прода; требует probeSpec)
visualEvidenceSuggestedNoTrue only when this AC accepts Planner's visual-AC advisory

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / visualEvidenceSuggested
      Added value: +{
+  "default": false,
+  "description": "True only when this AC accepts Planner's visual-AC advisory",
+  "type": "boolean"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / probeSpec / properties / method / enum
      Previous value: -[
-  "GET",
-  "HEAD",
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE"
-]New value: +[
+  "GET",
+  "HEAD"
+]
  3. Changed2 schema fields changed
    • addedInput schema / properties / probeClass
      Added value: +{
+  "default": null,
+  "description": "Класс критерия: pre-merge (default; доказывается в CI / приложенным evidence) или post-deploy (доказывается исполнимой пробой против прода; требует probeSpec)",
+  "enum": [
+    "pre-merge",
+    "post-deploy",
+    null
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / probeSpec
      Added value: +{
+  "default": null,
+  "description": "Исполнимая проба post-deploy критерия: {method: GET|HEAD|POST|PUT|PATCH|DELETE, url: абсолютный http(s), expect: {http_code: 200, body: {field: expectedValue, nested: {field: value}}}}. Ожидаемые значения фиксируются сейчас; единственная подстановка времени прогона — \"{{deployed_revision}}\" (SHA развёрнутой ревизии). Пример: {\"method\":\"GET\",\"url\":\"https://planner.monopoly-gold.com/api/healthz\",\"expect\":{\"http_code\":200,\"body\":{\"status\":\"ok\",\"revision\":\"{{deployed_revision}}\"}}}",
+  "properties": {
+    "expect": {
+      "description": "What the response must contain: http_code (exact) and/or body (subset of fields with expected scalar values; nested objects = nested fields; \"{{deployed_revision}}\" = SHA of the revision that triggered the probe)",
+      "properties": {
+        "body": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "http_code": {
+          "maximum": 599,
+          "minimum": 100,
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    },
+    "method": {
+      "description": "HTTP method of the probe request",
+      "enum": [
+        "GET",
+        "HEAD",
+        "POST",
+        "PUT",
+        "PATCH",
+        "DELETE"
+      ],
+      "type": "string"
+    },
+    "url": {
+      "description": "Absolute http(s) URL the runner requests on the deployed instance",
+      "type": "string"
+    }
+  }
+}
  4. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only say readOnly=false and non-idempotent=false; description goes far beyond: it discloses rejection behavior (error=probe_required), the implicit assignment of probeClass when probeSpec is present, the linter behavior in Grove mode, the frozen-edits rule, and the special recheck flow for visual advisories. This is exactly the kind of behavioral context the annotations don't cover.

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 dense and long, but every sentence contributes necessary operational knowledge. It front-loads the core contract (append + observable check) before diving into modes and constraints. Slightly heavy for a first scan, but the density is purposeful.

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?

Covers the full calling context: return value (criterion id, class, probeSpec, quality findings), mode-dependent behavior (Grove vs non-Grove), linter behavior, required probeSpec for post-deploy, and the visual-evidence adoption path. An agent can select and invoke this tool correctly without further external context.

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

Parameters5/5

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

Though the schema describes each parameter well, the description adds semantic meaning beyond field names:

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 imperative verb and resource: 'Append an acceptance criterion to a goal.' It then defines what a criterion is (an observable check over an artifact) with a concrete example, which disambiguates the tool from generic goal-update or goal-create operations.

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?

Explicitly distinguishes pre-merge vs post-deploy classes, states when probeSpec is required, and explains when visualEvidenceSuggested should be set (only when adopting a suggestion from goal-create/goal-get/ready_for_work). Gives clear constraints per mode (Grove: AC only editable in backlog) and notes the visual advisory flow — no ambiguity about when to use this tool.

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