Skip to main content
Glama

Ambr

by io.github.getambr

ambr_create_contract

Generate a Ricardian Contract from a template.

Creates a dual-format contract (human-readable legal text + machine-parsable JSON) using AI, linked by SHA-256 hash. The contract is stored on Ambr and accessible via the Reader Portal.

Requires a valid API key (X-API-Key header on the HTTP request) with available credits. Use ambr_list_templates first to discover templates and their required parameters.

Args:

  • template (string, required): Template slug (e.g. "d1-general-auth")

  • parameters (object, required): Template-specific parameters matching the schema

  • principal_declaration (object, required): { agent_id, principal_name, principal_type }

  • parent_contract_hash (string, optional): SHA-256 hash of parent contract for amendments

  • oversight_threshold_usd (number, optional): spending level above which work created under this contract needs human approval. Children exceeding it halt at awaiting_principal_approval.

  • amendment_type (string, optional): "original" | "amendment" | "extension"

Returns:

  • contract_id: Unique ID (e.g. "amb-2026-0042")

  • sha256_hash: SHA-256 hash for verification

  • status: Contract status

  • reader_url: URL to view in Reader Portal

  • credits_remaining: Remaining API credits

Legibility: Output is dual-format by construction and replayable to the original SHA-256 hash — the basis of Ambr's legibility guarantee.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
templateYesTemplate slug from ambr_list_templates
parametersYesTemplate-specific parameters
amendment_typeNo
parent_contract_hashNoSHA-256 hash of parent contract (for amendments)
principal_declarationYes
oversight_threshold_usdNoSpending level above which work created UNDER this contract requires human approval. A child contract exceeding the parent threshold is held at awaiting_principal_approval until a human signs, and cannot be signed or activated before then (EU AI Act Art. 14).

TDQS

A4.7/5.0
Behavior5/5

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

The description discloses meaningful non-annotation behavior: the contract is generated by AI, stored on Ambr, accessible via Reader Portal, and requires API key/credits. Return fields include credits_remaining, implying credit consumption, and the legibility guarantee is explicitly framed. The annotations give only false/neutral hints, so this description carries the behavioral disclosure burden well.

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?

The description is structured with a clear summary, Args/Returns/Legibility blocks, and prerequisites, so the information is easy to scan. Although fairly long, every block adds necessary operational or semantic detail, making the length justified.

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?

With no output schema, the description explicitly lists the expected return fields (contract_id, sha256_hash, status, reader_url, credits_remaining). It also covers authentication, required prerequisite steps, side effects, nested principal_declaration structure, and the oversight threshold behavior, so an agent has enough context to invoke it correctly.

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?

It adds value beyond the schema, giving a concrete template slug example, enumerating amendment_type values, and explaining the operational behavior of oversight_threshold_usd (children halting at awaiting_contract_signature until principal_requires_approval). The `parameters` object is still only loosely described as 'template-specific parameters matching the schema', but the requirement to list templates first compensates.

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 opens with a specific verb+resource: 'Generate a Ricardian Contract from a template.' It then clarifies what that means in concrete terms (dual-format, SHA-256-linked, stored on Ambr), which fully distinguishes it from the read/status/verify/list sibling tools.

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?

It explicitly instructs the agent to use ambr_list_templates first to discover templates and their parameters, and it states the prerequisite of a valid API key with available credits. It does not formally state when not to use this tool in favor of get/status/verify, but the creation context is sufficiently clear.

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

All Ambr toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.3/5.0
Disambiguation4/5

Most tools have clearly distinct purposes: create, retrieve, list templates, verify, and handshake are separate actions. The main confusion risk is between ambr_get_contract and ambr_get_contract_status, both take an id and return contract state, though the status tool emphasizes amendment-chain history.

Naming Consistency4/5

The ambr_ prefix and snake_case convention are applied consistently, with clear verb-like action words for most tools. ambr_agent_handshake deviates slightly from the clean verb_noun pattern, but the overall naming remains predictable.

Tool Count5/5

Six tools is a well-scoped size for a contract-management domain. Each tool covers an essential interaction: template discovery, contract creation, retrieval, status checking, hash verification, and counterparty handshake communication.

Completeness4/5

The core lifecycle is covered well: create, retrieve, check status, verify, and act on a contract. Notable gaps include no tool to list a user's own contracts or explicitly terminate one, but these can be worked around or may be intentionally handled outside the API since contracts are likely immutable.

Resources