writ-mcp

Official

Overview Schema Source Related Servers Discussions Admin

writ_execute

Run one policy-gated upstream API request with a lease or ALLOW token. It verifies method, path, and body match before forwarding; mismatches fail closed.

Instructions

Run one gated upstream request with a lease or ALLOW token.

Pass exactly one of lease_id (from writ_lease) or auth_token (from a writ_check ALLOW). Pass the SAME method, path, and body as the lease: the gate compares the request bytes against the lease, and on any mismatch it fails closed: no upstream call is made and the answer is {"ok": false, "reason": ..., "upstreamCalled": false}.

Args: lease_id: The leaseId from writ_lease. Mutually exclusive with auth_token. auth_token: An ALLOW authToken from writ_check. Mutually exclusive with lease_id. system_id: The registered upstream system: "stripe" (default), "github", or "salesforce". method: HTTP method of the upstream request (required, e.g. "POST"). path: Upstream path (required, e.g. "/v1/refunds"). body: Optional JSON object. Must be byte-identical to the leased body. idempotency_key: Optional key passed through to the upstream system. Use it so retries are safe.

On success the gate returns the upstream system's status and body verbatim. Every outcome writes a receipt. On {"ok": false} report the reason to the user and do NOT retry with a different request: the lease is spent or invalid.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "writ_execute"
  }
}

Input Schema

Name	Required	Default
`body`	No
`path`	No
`method`	No
`lease_id`	No
`system_id`	No	stripe
`auth_token`	No
`idempotency_key`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.15Nov 12, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are supplied, so the description carries the full behavioral burden and does so: it discloses fail-closed gate semantics ("no upstream call is made"), byte-comparison of method/path/body against the lease, receipt writing for every outcome, verbatim upstream status and body on success, and the fact that a failed lease is spent. It also recommends idempotency_key so retries are safe, which is non-obvious operational guidance for a mutating call.

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 structure is sound: purpose first, then the matching rule, then a parameter block, then outcome behavior. The Args block restates parameter names already visible in the schema, but each entry adds real semantics, so the repetition is mostly earned rather than 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 7-parameter gated mutation with no annotations, the description covers everything an agent needs: where each credential comes from, valid system targets, the byte-identical requirement, and what to do on failure. An output schema exists, and the description still states the success and failure shapes without over-explaining return values.

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?

Schema description coverage is 0%, so the description must compensate and it does for all seven parameters: mutual exclusivity of lease_id/auth_token, the enum-like valid values for system_id with its "stripe" default, method/path examples, and the byte-identical constraint on body. This is meaning well beyond what the bare schema titles provide.

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 first sentence states a specific verb and resource: "Run one gated upstream request with a lease or ALLOW token." It immediately distinguishes this from the upstream setup siblings by naming the credential sources (writ_lease for leases, writ_check for ALLOW tokens), so an agent can tell whether it is executing or still authorizing.

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?

It gives explicit preconditions ("Pass exactly one of lease_id ... or auth_token"), names the sibling tools that produce each credential, and states an exclusion rule for failure: "On {"ok": false} report the reason to the user and do NOT retry with a different request: the lease is spent or invalid." Both the when and the when-not are covered.

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