Shodai Agreements
Server Details
Author, validate, deploy, and operate Shodai on-chain agreements.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.3/5 across 11 of 11 tools scored.
Each tool has a clearly distinct purpose: deployment, retrieval, validation, typed data preparation, submission, and listing. No two tools overlap in functionality; even the two validation-like tools (validate_agreement and preflight_deployment) are explicitly differentiated by scope.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., deploy_agreement, get_agreement, list_agreements, validate_agreement). The verbs are appropriate and predictably describe the action.
With 11 tools, the set is well-scoped for managing on-chain agreements. Each tool serves a necessary step in the workflow (validation, preparation, deployment, reading, input submission, history), and there is no bloat or redundancy.
The tool surface covers the entire lifecycle: JSON validation, deployment readiness checks, typed data preparation, deployment, retrieval of agreement and document, state queries, input submission, and history inspection. No obvious gaps exist for the intended domain.
Available Tools
11 toolsdeploy_agreementDeploy agreementADestructiveInspect
Deploys authored agreement JSON using an EIP-712 permit; the API submits the on-chain transaction and returns the deployed agreement record. Provide a pre-signed permit (signer, deadline, signature), or call prepare_deployment_typed_data first to obtain the payload to sign. Always run preflight_deployment before deploying. Requires the agreements.write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| docUri | No | Optional document URI recorded on-chain with the agreement. | |
| signer | No | Wallet address (0x...) that signed the permit. | |
| chainId | No | Target EVM chain ID (e.g. 59141 for Linea Sepolia). | |
| deadline | No | Permit deadline in unix seconds. Must match the signed payload. | |
| agreement | Yes | Complete authored agreement JSON document with metadata, variables, content, and execution sections. | |
| observers | No | Observer email addresses. | |
| documentId | No | Optional hosted document ID paired with docUri for GET /v0/agreements/documents/{documentId}. | |
| initValues | No | Deployment-time values for variables referenced by execution.initialize.data. | |
| signatureR | No | Permit signature r component (0x... 32 bytes). | |
| signatureS | No | Permit signature s component (0x... 32 bytes). | |
| signatureV | No | Permit signature v component (27 or 28). | |
| displayName | Yes | Human-readable name for the deployed agreement record. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. | |
| participants | No | Wallet mappings for participant variables. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false. Description adds context about the permit process, requirement to run preflight, and scope, which is valuable. However, it does not elaborate on side effects like what happens on failure or whether existing records are affected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each essential: first states the core action, second explains the permit preparation options, third gives the mandatory prerequisite. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 params, nested objects, no output schema), the description covers the main flow, prerequisites, and scope. It could mention what the returned record contains, but overall it is sufficiently complete for an experienced developer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description does not need to compensate heavily. It adds context for the permit-related parameters (signer, deadline, signature) and links to prepare_deployment_typed_data, but doesn't explain each parameter's semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool deploys an agreement JSON using EIP-712 permit and submits an on-chain transaction. It distinguishes from siblings like preflight_deployment and prepare_deployment_typed_data by describing its role as the final deployment step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use guidance: provide a pre-signed permit or call prepare_deployment_typed_data first. Also mandates running preflight_deployment before deploying and mentions required scope (agreements.write).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_agreementGet agreementARead-onlyIdempotentInspect
Returns a single agreement record, including the full authored agreement JSON and hosted record context (participants, observers, owner, deployment address).
| Name | Required | Description | Default |
|---|---|---|---|
| agreementId | Yes | Agreement record ID, as returned by list_agreements (not the on-chain address). | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds value by specifying what the response includes (authored JSON, context). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single 22-word sentence that is front-loaded and contains no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read-only, two required params, no output schema), the description completely covers what the tool does and what the output contains. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description does not add additional meaning beyond what the schema already provides, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a single agreement record with specific content ('full authored agreement JSON and hosted record context'), distinguishing it from sibling tools like list_agreements (which returns multiple) and deploy_agreement (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via its purpose (retrieve a single record by ID) but does not explicitly state when to use this versus alternatives or when not to use it. No guidance on context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_agreement_documentGet agreement documentARead-onlyIdempotentInspect
Returns the rendered hosted prose document for an agreement by documentId, including content type, display name, chain, docUri, and agreement record references. Use documentId from list_agreements/get_agreement or from prepare_deployment_typed_data.
| Name | Required | Description | Default |
|---|---|---|---|
| documentId | Yes | Hosted agreement document ID, as returned by list_agreements/get_agreement or prepare_deployment_typed_data. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, and non-destructive, so safety is known. The description adds behavioral detail by listing the specific fields returned and the source of the input ID, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each delivering essential information: the first explains the function and output, the second provides input guidance. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists key fields returned (content type, display name, chain, docUri, agreement record references). While it does not specify the format or structure, it is sufficiently complete for a read-only retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters thoroughly. The description restates the source of documentId but adds no new semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a rendered hosted prose document by documentId, listing included fields. It distinguishes from sibling get_agreement by specifying it returns the document content, not just agreement metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells where to obtain the documentId (from list_agreements/get_agreement or prepare_deployment_typed_data). However, it does not provide guidance on when not to use this tool or contrast it with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_agreement_stateGet agreement stateARead-onlyIdempotentInspect
Returns the current state of an agreement. For deployed agreements, interpret the state against the states defined in the authored agreement lifecycle (execution.states). Use this to poll for transitions after submitting an input.
| Name | Required | Description | Default |
|---|---|---|---|
| agreementId | Yes | Agreement record ID, as returned by list_agreements (not the on-chain address). | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining that the state should be interpreted against the authored lifecycle for deployed agreements, and it is consistent with readOnlyHint, idempotentHint, and destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose, and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only poll tool with strong annotations, the description sufficiently explains the return value and usage. No output schema exists, but the description provides adequate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current state of an agreement and specifies its use for polling after submitting input, effectively distinguishing it from siblings like get_agreement and submit_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states to use this tool for polling after submitting an input, providing clear context. However, it does not explicitly list when not to use it or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_input_historyGet input historyARead-onlyIdempotentInspect
Returns recorded input submissions for an agreement, with pagination and filtering. Use this to inspect which events have been submitted and whether each is PENDING, MINED, or FAILED.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size (max 100). | |
| cursor | No | Opaque pagination cursor from a previous response (pageInfo.nextCursor). | |
| status | No | Filter by submission status. | |
| inputId | No | Filter by input ID as defined in the agreement JSON (execution.inputs). | |
| agreementId | Yes | Agreement record ID, as returned by list_agreements (not the on-chain address). | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, covering safety. The description adds behavioral details: pagination, filtering, and status values, which enrich understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences), front-loading the core purpose and key features (pagination, filtering, statuses). No word is wasted, earning a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool has good annotations and full schema coverage, there is no output schema. The description mentions statuses but omits response structure (e.g., fields like records, pageInfo, total count), leaving the agent partially uninformed about the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already documents each parameter fully. The description repeats the high-level purpose but adds no specific meaning beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'returns' and the resource 'recorded input submissions for an agreement', with specific scope including pagination and filtering. It distinctly differentiates from siblings like submit_input (write) and get_agreement (agreement details), as it focuses on input submission history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage scenario ('Use this to inspect which events have been submitted and whether each is PENDING, MINED, or FAILED'), but does not explicitly state when not to use it or suggest alternatives from sibling tools, leaving the agent to infer usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_agreementsList agreementsARead-onlyIdempotentInspect
Lists agreement summaries visible to the current API key. Supports pagination (cursor + limit), filtering by chain and state, and sorting. Returns summaries only; use get_agreement for the full record.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size (max 100). | |
| state | No | Filter by current lifecycle state ID. | |
| cursor | No | Opaque pagination cursor from a previous response (pageInfo.nextCursor). | |
| sortBy | No | Sort field (single field only). | |
| chainId | No | Filter by EVM chain ID (e.g. 59141 for Linea Sepolia). | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. | |
| createdAfter | No | ISO 8601 timestamp; only agreements created at or after this time. | |
| updatedAfter | No | ISO 8601 timestamp; only agreements updated at or after this time. | |
| createdBefore | No | ISO 8601 timestamp; only agreements created at or before this time. | |
| sortDirection | No | Sort direction; defaults to desc. | |
| updatedBefore | No | ISO 8601 timestamp; only agreements updated at or before this time. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by specifying that it returns summaries (not full records), supports pagination, filtering, and sorting, and is scoped to the current API key's visibility. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. First sentence states the core action, second sentence adds key features and an alternative. Very concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (all schema-described), no output schema, and comprehensive annotations, the description adequately covers the tool's purpose, scope (API key visibility), features (pagination, filtering, sorting), and guidance for full records. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description summarizes that it supports pagination, filtering by chain and state, and sorting, but does not add specific details beyond what is in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'lists', resource 'agreement summaries', and scope 'visible to the current API key'. It also distinguishes from sibling tool 'get_agreement' by noting it returns summaries only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Returns summaries only; use get_agreement for the full record', providing explicit guidance on when to use this tool vs a key sibling. It also mentions supported features (pagination, filtering, sorting), though it does not cover other sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preflight_deploymentPreflight deployment requestARead-onlyIdempotentInspect
Checks whether authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context are ready for deployment. This does not deploy the agreement and does not require a signature. Always run this before signing a deploy permit. Requires the agreements.write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| chainId | No | Target EVM chain ID for deployment. | |
| agreement | Yes | Complete authored agreement JSON document with metadata, variables, content, and execution sections. See the simple/complex example resources for the authoritative shape. | |
| observers | No | Observer email addresses for the deployed agreement. | |
| initValues | No | Deployment-time values for variables referenced by execution.initialize.data. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. | |
| participants | No | Wallet mappings for participant variables. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Aligns with annotations (readOnlyHint=true, destructiveHint=false) by confirming no deployment and no signature. Adds context about requiring 'agreements.write' scope. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct value: what the tool does, what it doesn't do, and when to use it. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description doesn't explain return values, but the tool's purpose is clear. For a preflight check, this is sufficient. Could mention what the tool returns (e.g., success/failure details) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds marginal value. It names parameter categories ('target chain, deployment values, participant wallet mappings, observer context') which reinforces the schema but doesn't provide new details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Checks' and specifies the resource ('authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context'). It clearly distinguishes itself from sibling tools like 'deploy_agreement' by stating 'This does not deploy the agreement and does not require a signature.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Always run this before signing a deploy permit,' implying it is a prerequisite. It also lists required scope. While it doesn't explicitly mention when not to use, the context of being a pre-check is clear. Could be improved by mentioning alternatives like 'validate_agreement' for different validation needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
prepare_deployment_typed_dataPrepare deployment permit typed dataARead-onlyIdempotentInspect
Builds the exact EIP-712 payload that must be signed to authorize deployment of the given agreement JSON. Sign the returned typedData with the deploying wallet (eth_signTypedData_v4 / viem signTypedData), then call deploy_agreement with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the signer nonce from the target chain.
| Name | Required | Description | Default |
|---|---|---|---|
| docUri | No | Document URI (must match the later deploy_agreement call). | |
| chainId | Yes | Target EVM chain ID (e.g. 59141 for Linea Sepolia). | |
| deadline | No | Permit deadline in unix seconds; defaults to one hour from now. | |
| agreement | Yes | Complete authored agreement JSON document with metadata, variables, content, and execution sections. | |
| observers | No | Observer email addresses. | |
| documentId | No | Hosted document ID. If omitted with docUri, no hosted document ID is stored; if both are omitted, the server generates both values. | |
| initValues | No | Deployment-time init values (must match the later deploy_agreement call). | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. | |
| participants | No | Wallet mappings for participant variables. | |
| signerAddress | Yes | Wallet address (0x...) that will sign and own the deployment. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: 'No transaction is sent and nothing is stored. Reads the signer nonce from the target chain.' This confirms read-only behavior and reveals an external call, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: three sentences efficiently cover purpose, usage flow, behavioral traits, and nonce read. It is front-loaded with the primary action and includes no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 10 parameters and nested objects, the description omits the output format. It mentions 'returned typedData' but does not describe its structure. Without an output schema, the agent may need to infer the shape from the sibling deploy_agreement. The description covers essential flow but lacks details on return value format or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds cross-parameter constraints, e.g., 'docUri must match the later deploy_agreement call' and 'initValues must match the later deploy_agreement call.' This adds value beyond the schema by linking parameters to the sibling tool's requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Builds the exact EIP-712 payload that must be signed to authorize deployment of the given agreement JSON.' It specifies the verb (builds), the resource (EIP-712 payload), and the context (authorize deployment). It distinguishes itself from the sibling deploy_agreement by describing its role as a preparatory step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: sign the returned typedData with the deploying wallet using eth_signTypedData_v4/viem signTypedData, then call deploy_agreement. It also states what the tool does not do (no transaction sent, nothing stored). It lacks explicit when-not-to-use or alternatives, but the flow is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
prepare_input_typed_dataPrepare input permit typed dataARead-onlyIdempotentInspect
Builds the exact EIP-712 payload that must be signed to authorize submitting an input to a deployed agreement. Sign the returned typedData with a wallet allowed by the input definition, then call submit_input with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the agreement record and signer nonce.
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | Values matching the input schema (must match the later submit_input call). | |
| inputId | Yes | Input ID defined by the agreement JSON (execution.inputs). | |
| deadline | No | Permit deadline in unix seconds; defaults to one hour from now. | |
| agreementId | Yes | Agreement record ID of a deployed agreement. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. | |
| signerAddress | Yes | Wallet address (0x...) that will sign the input permit. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare it read-only, idempotent, and non-destructive. The description adds behavioral context: no transaction sent, nothing stored, reads agreement record and signer nonce. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the main action, then provide instructions and behavioral notes. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value (typedData), prerequisites, next steps, and behavioral traits. It is fully complete for a preparation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by stating the deadline defaults to one hour and that values must match the later submit_input call, beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds the exact EIP-712 payload for signing to authorize input submission, with a specific verb and resource. It distinguishes from sibling tools like submit_input and deploy_agreement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear workflow: sign the returned typedData, then call submit_input with specific components. It implies when to use this tool (preparation) and what follows (submission), but lacks explicit 'when not to use' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_inputSubmit input with permitADestructiveInspect
Submits a signed input to a deployed agreement, advancing its on-chain lifecycle. The input ID and values must match an input defined by the agreement JSON, and the signer must be allowed by that input. Provide a pre-signed permit (signer, deadline, signature), or call prepare_input_typed_data first. Requires the agreements.write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| signer | No | Wallet address (0x...) that signed the permit. | |
| values | Yes | Values matching the input schema defined by the agreement JSON. | |
| inputId | Yes | Input ID defined by the agreement JSON (execution.inputs). | |
| deadline | No | Permit deadline in unix seconds. Must match the signed payload. | |
| signatureR | No | Permit signature r component (0x... 32 bytes). | |
| signatureS | No | Permit signature s component (0x... 32 bytes). | |
| signatureV | No | Permit signature v component (27 or 28). | |
| agreementId | Yes | Agreement record ID of a deployed agreement. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining that the tool advances the on-chain lifecycle and requires the agreements.write scope. Annotations indicate destructiveness, and the description confirms this. It also explains the permit mechanism, which is not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences. The main action is stated first, followed by prerequisites and an alternative. There is no unnecessary information, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (9 parameters, nested objects, no output schema), the description is somewhat complete but lacks information about what the tool returns (e.g., success indication or transaction hash) and behavior on failure. It adequately covers input requirements but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds some contextual meaning by relating the input ID and values to the agreement JSON and mentioning the permit components (signer, deadline, signature). However, it does not provide detailed semantics beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits a signed input to a deployed agreement, advancing its on-chain lifecycle. It uses a specific verb and resource, and distinguishes itself from sibling tools like prepare_input_typed_data by mentioning it as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it requires a deployed agreement, matching input IDs and values, and a pre-signed permit. It explicitly names prepare_input_typed_data as an alternative for creating the permit, and mentions the required scope. However, it does not explicitly state when not to use it or exclude specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_agreementValidate agreement structureARead-onlyIdempotentInspect
Checks only the authored agreement JSON document and returns participant variable keys, input IDs, state IDs, and warnings. This does not validate deployment values, participant wallet addresses, signer, or permit data — use preflight_deployment for that. Iterate on the agreement JSON until this returns no blocking warnings. Requires the agreements.write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| agreement | Yes | Complete authored agreement JSON document with metadata, variables, content, and execution sections. See the simple/complex example resources for the authoritative shape. | |
| environment | Yes | Agreements API environment for this tool call. API keys only work in the environment where they were created. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive. The description adds context about requiring the agreements.write scope and describes output items, which supplements the annotation information. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no unnecessary words. Each sentence serves a distinct purpose: defining scope, clarifying exclusions, and providing usage instruction. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes return items. For a validation tool with two well-documented parameters and clear purpose, coverage is excellent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both 'agreement' and 'environment' are described in the schema). The description does not add additional parameter-level meaning beyond schema, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks agreement JSON structure, names the returned items (variable keys, IDs, warnings), and explicitly distinguishes from preflight_deployment. It uses specific verbs and resources, making it distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: iterate on agreement until no blocking warnings, requires agreements.write scope, and excludes deployment validation. It clearly states when to use (for structure validation) and when to use preflight_deployment instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!