Skip to main content
Glama

ZeroWidth

by ai.zerowidth
OverviewDiscussionsAdmin

Pre-register an experiment's expectation

compass_opportunities_register_expectation

The honesty mechanism: write what the experiment is expected to change BEFORE evidence exists. Creates a Ledger decision entry and links it to the opportunity — never backfill an expectation to match an outcome. Bind a metric (ledger_metrics_list) + comparator + target when the expectation is measurable; readings then land on the entry as evidence automatically. One expectation per opportunity — revise by superseding in Ledger. May return needs_confirmation.

Input Schema

NameRequiredDescriptionDefault
targetNoTarget value, in the metric's unit (hours for time).
deadlineNoISO date the expectation is due by.
metricIdNoLedger metric to bind (requires target). From ledger_metrics_list.
workspaceNoWorkspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.
approvalIdNoApproval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.
comparatorNo
fromRollupNoInstead of metricId: measure it off the change's workflow roll-up — a step's (nodeId) or the whole workflow's hands-on time, waiting, labor, or hard cost, per run or per month. Creates a daily-fed metric with the last 30 days rebuilt from the map's history, so the before is on record. Needs a target; comparator defaults to <=.
expectationYesOne sentence — what we expect this to change.
opportunityIdYesThe change's key (e.g. ACME-12) or id, from compass_opportunities_list.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / fromRollup
      Added value: +{
+  "description": "Instead of metricId: measure it off the change's workflow roll-up — a step's (nodeId) or the whole workflow's hands-on time, waiting, labor, or hard cost, per run or per month. Creates a daily-fed metric with the last 30 days rebuilt from the map's history, so the before is on record. Needs a target; comparator defaults to <=.",
+  "properties": {
+    "bound": {
+      "default": "mid",
+      "enum": [
+        "low",
+        "high",
+        "mid"
+      ],
+      "type": "string"
+    },
+    "currency": {
+      "pattern": "^[A-Z]{3}$",
+      "type": "string"
+    },
+    "field": {
+      "enum": [
+        "working",
+        "waiting",
+        "labor",
+        "hardCost"
+      ],
+      "type": "string"
+    },
+    "nodeId": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    },
+    "scope": {
+      "default": "perRun",
+      "enum": [
+        "perRun",
+        "perMonth"
+      ],
+      "type": "string"
+    },
+    "variantId": {
+      "maxLength": 64,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "field"
+  ],
+  "type": "object"
+}
    • changedInput schema / properties / target / description
      Previous value: -"Target value, in the metric's unit."New value: +"Target value, in the metric's unit (hours for time)."
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations only cover the safety profile (readOnly=false, destructive=false). The description adds real behavioral context beyond that: it creates a linked Ledger decision entry, readings flow in automatically as evidence, revisions happen by superseding, and it may return needs_confirmation. It doesn't fully explain the confirmation/approval round-trip, keeping it from a 5.

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?

Front-loads the core purpose in the first clause, then layers conditions and mechanics in tight, waste-free sentences. No filler, and the honesty framing is placed where an agent reads first.

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?

No output schema exists, and the description does cover the notable return case (needs_confirmation) plus the downstream evidence behavior. For a 9-parameter tool with a nested object and an approval flow, it is nearly complete, lacking only explicit guidance on the approvalId sequencing.

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 high (89%), so baseline is 3, but the description adds meaning beyond the schema by tying metricId + comparator + target together as a binding unit and clarifying the evidence flow. The per-parameter details (target, deadline, fromRollup) are already well documented in the schema.

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?

States a specific verb (pre-register/write) and resource (an experiment's expectation on an opportunity), and frames the unique value proposition ('the honesty mechanism') that no sibling offers. An agent can distinguish it from compass_opportunities_create or ledger_entries_create without opening any schema.

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?

Gives clear timing ('BEFORE evidence exists', 'never backfill') and names the related tools (ledger_metrics_list) needed to make the expectation measurable, plus the one-per-opportunity rule with the supersede-in-Ledger alternative. It stops short of explicitly stating when to prefer this over a plain ledger entry or opportunity update, so it is clear context but without full exclusions.

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

All ZeroWidth 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