Tirith

Official

Overview Schema Source Related Servers Discussions Admin

contract_publish

Publish an interface shape before either side implements it, track consuming paths, and create versions with change notices so parallel agents avoid conflicts.

Instructions

Publish the shape of an interface (an endpoint, function, type, event or CLI) before either side implements it, with the paths that will consume it. Publishing an existing name creates a new version and sends its consumers a change notice by itself, so do not also call notice_publish. Omitting consumers on a republish keeps the list, and expected_version refuses the write with conflict if another agent published first. Lead-only while a swarm has a lead. To read contracts use contract_get or contract_list.

Input Schema

Name	Required	Description
`kind`	Yes	One of `http`, `function`, `type`, `event`, `cli`, `other`.
`name`	Yes	Unique contract name, for example `POST /api/sessions` or `State::claim`.
`agent`	Yes	Your stable agent name.
`notes`	No	Free-text notes stored with this version.
`shape`	Yes	The interface shape as JSON: signatures, request and response types, errors.
`consumers`	No	Paths expected to depend on this contract.
`expected_version`	No	Refuse unless the contract is at this version now (0 = absent).

Output Schema

Name	Required	Description
`lead`	No	On a lead-only conflict: the lead to message.
`status`	Yes	ok. conflict: expected_version was set and the contract is at another version, or lead-only. invalid: bad input.
`message`	No	Human-readable detail, on most outcomes other than ok.
`contract`	No	id, name, kind, consumers, current (version, shape, notes, published_by, published_at), history.
`notice_id`	No	The change notice emitted to consumers of a republished contract.
`published_by`	No	On conflict: who published that version.
`current_version`	No	On conflict: the version the contract is at.
`previous_version`	No	The version this one replaced; absent or null on a first publish.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.3.0Oct 16, 2026

addedOutput schema / properties / lead

Added value: +{
+  "description": "On a lead-only conflict: the lead to message."
+}

changedOutput schema / properties / status / description

Previous value: -"ok. conflict: expected_version was set and the contract is at another version. invalid: bad input."New value: +"ok. conflict: expected_version was set and the contract is at another version, or lead-only. invalid: bad input."

Changed9 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```

addedInput schema / properties / consumers / description

Added value: +"Paths expected to depend on this contract."

addedInput schema / properties / expected_version / description

Added value: +"Refuse unless the contract is at this version now (0 = absent)."

addedInput schema / properties / kind / description

Added value: +"One of `http`, `function`, `type`, `event`, `cli`, `other`."

addedInput schema / properties / kind / enum

Added value: +[
+  "http",
+  "function",
+  "type",
+  "event",
+  "cli",
+  "other"
+]

addedInput schema / properties / name / description

Added value: +"Unique contract name, for example `POST /api/sessions` or `State::claim`."

addedInput schema / properties / notes / description

Added value: +"Free-text notes stored with this version."

addedInput schema / properties / shape / description

Added value: +"The interface shape as JSON: signatures, request and response types, errors."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "contract": {
+      "description": "id, name, kind, consumers, current (version, shape, notes, published_by, published_at), history.",
+      "type": "object"
+    },
+    "current_version": {
+      "description": "On conflict: the version the contract is at.",
+      "type": "integer"
+    },
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "notice_id": {
+      "description": "The change notice emitted to consumers of a republished contract."
+    },
+    "previous_version": {
+      "description": "The version this one replaced; absent or null on a first publish."
+    },
+    "published_by": {
+      "description": "On conflict: who published that version."
+    },
+    "status": {
+      "description": "ok. conflict: expected_version was set and the contract is at another version. invalid: bad input.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only supply destructiveHint=false, so the description carries the real burden and does so: republishing an existing name creates a version and auto-notifies consumers, omitting consumers preserves the prior list, expected_version causes a conflict refusal on concurrent writes, and the operation is lead-only. These are non-obvious behaviors that materially change how an agent should call it.

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?

Front-loaded with purpose and dense with distinct operational facts; almost every clause earns its place (notice suppression, consumers retention, version conflict, lead-only, read alternatives). Some sentences run long and pack multiple constraints together, which costs it the top mark, but there is no 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?

Covers purpose, timing (publish before either side implements), side effects, concurrency semantics, permission constraints, and read alternatives. Since an output schema exists, the description need not describe return values, so nothing an agent needs to invoke this 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 the baseline is 3, but the description adds semantics the schema does not: omitting consumers on a republish keeps the existing list, and expected_version refuses the write with a conflict if another agent published first (schema only says 'Refuse unless...'). It adds moderate value on top of a fully documented 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 (Publish) and resource (the shape of an interface) and immediately enumerates the contract kinds it covers (endpoint, function, type, event, CLI). It also explicitly distinguishes itself from the read-side siblings by naming contract_get and contract_list at the end.

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?

Gives explicit when-not guidance ('do not also call notice_publish', since publishing auto-sends a change notice) and names the alternative read tools. It also states the precondition that the caller must be lead while a swarm has a lead, which is exactly the kind of routing constraint an agent needs.

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