Shodai Agreements

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

Annotations already set destructiveHint=true; description confirms on-chain submission. It adds context about the permit mechanism and preflight requirement. No contradictions, but lacks mention of gas costs or irreversibility.

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?

Four concise sentences, front-loaded with purpose. Every sentence adds value (what it does, how to use it, prerequisite, scope). 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?

Given the complexity (14 params, nested objects, on-chain destructive action), the description covers the workflow and dependencies. It does not detail the return format or error handling, but it's sufficient for correct tool invocation.

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 extra meaning for the permit parameters and initValues, explaining their role in the signing workflow. This is helpful beyond the schema.

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 deploys an authored agreement JSON using an EIP-712 permit, submits an on-chain transaction, and returns a record. It specifies the resource, action, and method, and distinguishes itself from siblings like validate_agreement and prepare_deployment_typed_data.

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?

Explicit guidance: provide a pre-signed permit or call prepare_deployment_typed_data first; always run preflight_deployment before deploying. Also notes the required 'agreements.write' scope. This clearly tells the agent when and how to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to restate safety. The description adds value by specifying what the returned record includes (authored agreement JSON, participants, observers, owner, deployment address). No contradictions 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?

The description is a single sentence that conveys all necessary information with no superfluous words. It is front-loaded with the main action and immediately useful details.

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 simple read-only tool with two well-documented parameters, the description fully explains what the tool returns. No output schema exists, but the description covers the return value comprehensively (full authored JSON and context). 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%, with clear descriptions for both parameters (agreementId and environment). The description does not add further parameter details beyond what the schema provides. Baseline score of 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 'Returns' and specifies the resource 'single agreement record', including its contents (full authored agreement JSON and hosted record context). This differentiates it from sibling tools like list_agreements (which returns multiple) and get_agreement_state (which returns only state).

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?

No explicit guidance on when to use this tool vs alternatives. It implies usage for retrieving a specific agreement's details, but does not mention when not to use (e.g., for state use get_agreement_state, for listing use list_agreements). The context signals show sibling tools, but the description misses the opportunity to clarify selection criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing the return content and references, without 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?

Two concise, front-loaded sentences that efficiently convey purpose and parameter sourcing with no wasted 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 adequately lists return fields and connects to sibling tools, making the tool's behavior clear.

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% and parameter descriptions are clear; the tool description adds minimal extra meaning beyond restating usage context.

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 'Returns the rendered hosted prose document for an agreement by documentId' and lists specific return fields, differentiating it from sibling tools like list_agreements.

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 guides where to obtain documentId (list_agreements/get_agreement or prepare_deployment_typed_data), but does not explicitly state when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds polling context but no additional behavioral traits beyond what annotations provide. 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?

Two sentences, front-loaded with the action, no fluff. 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?

Provides usage context (polling) and interpretation guidance (against lifecycle states). Lacks detail on output format or possible state values, but for a simple read tool this is adequate.

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 detailed descriptions for both parameters. Description does not add extra meaning beyond the schema, 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?

Description clearly states 'Returns the current state of an agreement' with a specific verb and resource. It distinguishes from siblings by mentioning polling use case, making the tool's purpose unambiguous.

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 advises using this tool to poll for transitions after submitting an input, and to interpret state against the lifecycle. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the status values (PENDING, MINED, FAILED) and the ability to filter, but does not discuss potential behaviors like response consistency or rate limits.

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 consists of two concise sentences. The first states the core function, and the second provides the use case. No unnecessary words or repetition.

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?

The description lacks detail about the output format (e.g., structure of returned submissions) and pagination mechanics (e.g., how cursor and limit interact). Given the tool's complexity (6 parameters, pagination, filtering), this is a notable gap, though annotations compensate for safety aspects.

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%, meaning the input schema already documents all parameters well. The description does not add new meaning beyond 'pagination and filtering,' which is generic. 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 specifies 'returns recorded input submissions for an agreement' with a clear verb and resource. It distinguishes itself from siblings like submit_input (which submits) and get_agreement (which gets agreement details), and mentions pagination and filtering capabilities.

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 states 'use this to inspect which events have been submitted and whether each is PENDING, MINED, or FAILED,' providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or list alternative tools for different scenarios.

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

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

Adds behavioral details beyond annotations: pagination (cursor + limit), filtering by chain and state, sorting, and that it returns summaries only. No contradictions with readOnlyHint, idempotentHint, destructiveHint=false.

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 clear sentences: first states purpose and scope, second lists features and alternative. No wasted words, front-loaded with key 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?

Covers essential context: visibility, pagination, filtering, sorting, and limitation to summaries. Without output schema, the note about summaries and the alternative for full records provides adequate completeness.

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%, baseline 3. Description adds value by grouping parameters into pagination, filtering, and sorting, explaining their combined purpose. Slight improvement over schema-only.

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?

Clearly states it lists agreement summaries visible to the current API key. Distinguishes from siblings by specifying return type and referencing get_agreement for full records.

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 to use get_agreement for full records, providing a clear alternative. Indicates pagination, filtering, and sorting capabilities, guiding when to use this tool for list operations.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive. The description reinforces these by stating it does not deploy or require a signature. No contradictions; the added scope requirement provides extra behavioral context.

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 short sentences, each serving a distinct purpose: purpose, non-action clarification, usage guidance and scope. Front-loaded with the core action, no wasted 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 covers the tool's purpose, usage order, and behavioral traits via annotations. It lacks explicit return value description but is sufficient for an agent to understand the tool's role in the workflow.

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 meaningfully aggregates parameters into the concept of 'readiness' for deployment, mapping agreement, chain, values, wallets, and observers to the tool's purpose, adding value beyond schema descriptions.

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 readiness of multiple components for deployment, using specific verbs and resources. It explicitly distinguishes from deployment and signature actions, and the sibling list confirms differentiation.

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 advises running this before signing a deploy permit, implying a specific workflow order. It mentions the required scope (agreements.write) but does not explicitly compare to similar tools like validate_agreement.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals that the tool reads the signer nonce from the target chain, which is a critical behavioral detail. It also confirms no state changes, fully aligning with and adding context to 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 three concise sentences, front-loading the purpose, then usage, then behavioral notes. Every sentence adds essential information without 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 complexity (10 parameters, nested objects), the description covers the core workflow and side effects. It could describe the output format of typedData more explicitly, but the annotations and schema provide sufficient context for an agent to invoke correctly.

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 baseline is 3. The description adds value by explaining relationships between parameters (e.g., docUri must match deploy_agreement, deadline defaults to one hour), which aids correct usage beyond the schema.

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 EIP-712 payload for signing, specifying the exact usage context (agreement deployment). It distinguishes itself from siblings by explicitly connecting to deploy_agreement and noting no transaction is sent.

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 explicit guidance on when to use this tool: to prepare typed data, then call deploy_agreement with the resulting components. It also clarifies what the tool does not do (no transaction, no storage), helping avoid misuse.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that 'No transaction is sent and nothing is stored. Reads the agreement record and signer nonce,' reinforcing the read-only and idempotent nature. 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?

The description consists of two concise sentences. The first clearly states the purpose, and the second provides actionable usage guidance. No redundant or unnecessary 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 no output schema, the description explains that the tool returns typedData, how to use it (sign and submit), and that it reads agreement record and signer nonce. With annotations covering safety and idempotency, this is fully complete for an agent.

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 documents all parameters. The description mentions 'signer, deadline, and the signature components' but does not add new meaning 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 'Builds the exact EIP-712 payload that must be signed to authorize submitting an input to a deployed agreement.' It uses a specific verb ('prepares') and resource ('typedData'), and distinguishes itself from sibling tools like submit_input by explaining it only prepares data for signing.

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 steps: 'Sign the returned typedData with a wallet allowed by the input definition, then call submit_input with signer, deadline, and the signature components.' It also notes that no transaction is sent and nothing is stored, indicating when to use this tool as a preparation step.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=false. Description adds context: it advances on-chain lifecycle, requires a permit, and that the signer must be allowed. It mentions scope requirement. No contradictions. It could elaborate on the exact state transition, but overall good transparency 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?

Description is two sentences plus scope requirement, with no redundancy. Every sentence provides essential information: what the tool does, prerequisites, and how to provide the permit. No filler.

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 write tool with 9 parameters and no output schema, description covers prerequisites and behavior well but omits return value or success/failure indicators. The description mentions 'advancing lifecycle' but does not clarify output format (e.g., transaction hash). Completeness is adequate but not full.

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 baseline is 3. The description groups parameters (e.g., permit components) and explains the overall flow, but does not add detailed semantics beyond the schema's own descriptions for each parameter. Minor added value in explaining how permit fields interrelate.

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 explicitly states the tool 'submits a signed input to a deployed agreement, advancing its on-chain lifecycle.' The verb 'submits' and resource 'signed input to a deployed agreement' are specific. It distinguishes from siblings like 'prepare_input_typed_data' by mentioning permit preparation, and from read tools by noting lifecycle advancement.

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?

Description provides clear context: the tool is used when you have a signed permit (or can call prepare_input_typed_data first). It specifies prerequisites like matching input ID and values, signer permissions, and required scope 'agreements.write.' It implies when not to use (if no permit) by suggesting the alternative prepare-input-typed-data, though not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context about return values and warnings, and that it does not validate deployment or signer data. 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-loaded with purpose, no wasted words. Each sentence provides essential 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?

Completely covers what the tool does, what it returns, its limitations, and usage instructions. No output schema, so description adequately explains return values.

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. Description adds value by describing the agreement JSON as 'complete authored agreement JSON document' and referencing example resources, which helps with the complex nested object parameter.

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?

Clearly states it checks the authored agreement JSON and returns participant variable keys, input IDs, state IDs, and warnings. Distinguishes from preflight_deployment by specifying what it does not validate.

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 says when to use (iterate until no blocking warnings) and when not to (use preflight_deployment for deployment validation). Also 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.