idios
Server Quality Checklist
Latest release: v3.4.0
- Disambiguation4/5
Each tool maps to a distinct contract lifecycle action or query, and the descriptions are highly specific, making misselection unlikely. A few pairs share similar name prefixes (claim_funds vs claim_after_timeout, the void_* tools) but their conditions and roles are clearly delineated.
Naming Consistency2/5The tool names mix verb_noun (create_contract_b, view_contract, claim_funds) with noun_verb (worker_register, worker_deregister, worker_reclaim, treasury_sweep) and a few irregulars (mutual_cancel, claim_after_timeout, void_claim_requester). This inconsistency makes it harder to predict tool names.
Tool Count3/526 tools is on the heavy side, somewhat above the typical 3-15 range, but the broad scope (contract lifecycle, dispute resolution, worker bonds, marketplace discovery) justifies most of them. It feels slightly over-scoped but still manageable.
Completeness4/5The tool surface covers the full escrow lifecycle: create, commit, deliver, approve, dispute, claim, refund, void, plus worker bond registration/reclaim and marketplace discovery. Minor gaps include no way to list a user's contracts or cancel an Open contract before expiry, but these can be worked around by tracking job IDs or waiting for expiry.
Average 4.7/5 across 26 of 26 tools scored. Lowest: 4/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 97 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that the call is read-only and does not require wallet funds, which are key behavioral traits. Also lists status values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise with each sentence adding value. It lists fields, statuses, usage, and read-only nature without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It provides adequate context (read-only, no funds, status enum) for a simple tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter job_id with no description. The tool description does not add any additional meaning to this parameter, and schema coverage is 0%. A brief explanation of job_id would improve this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'current on-chain state of an Idios contract', and lists the fields returned. It distinguishes from sibling tools like view_dispute and view_worker_reputation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to check contract state before deciding what action to take', providing clear when-to-use guidance. Does not mention when not to use or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains key consequences: locking dispute_fee, on-chain voting, finality of resolution, and allocation of dispute fee to arbitrators. It also directs users to 'view_dispute' for updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs for purpose, condition, process, post-action, and parameter. It is reasonably concise, though some details (e.g., 'Alice' specification) could be streamlined without loss of meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no annotations), the description covers purpose, use case, process, outcome, and next steps. It lacks explicit mention of prerequisites or permissions but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It simply states 'job_id: The contract ID to dispute.' This adds minimal context beyond the schema (which says 'Job Id'). A more detailed explanation (e.g., format, source) would improve clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('dispute'), resource ('delivered Mode B contract'), and actor ('as the requester (Alice)'). It also distinguishes from sibling tools like 'approve_delivery' and 'void_dispute' by specifying when to use ('if the deliverable does not meet the agreed specification').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('if the deliverable does not meet the agreed specification') and provides post-dispute instructions (contact arbitrator). However, it does not explicitly state when not to use it or mention alternatives beyond the contact step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: returns full payment, amount read from chain, can only be claimed once, and dispute fee forfeited. It omits side effects on chain state beyond 'can only be claimed once', but this is adequately implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences with front-loaded purpose, followed by preconditions and details. No unnecessary words; efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no annotations, output schema present), the description is complete. It covers when to use, the parameter, and behavioral notes. Lacks mention of potential errors beyond 'error message' but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to the single parameter job_id as 'The Voided contract ID to reclaim payment from', which is sufficient for understanding and use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'reclaim', resource 'payment from voided contract', and actor 'requester (Alice)'. It distinguishes from siblings like claim_funds and claim_after_timeout by targeting voided contracts and specifying the requester role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('after a stale dispute was voided via void_dispute') and notes that the dispute fee is forfeited, providing a clear constraint. However, it does not explicitly mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully discloses behavior: halting conditions based on cooldown, disputes, slashing, and return value. It comprehensively covers what happens in various states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but necessary to explain multiple conditions. It is front-loaded with the core purpose and logically structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no annotations, the description provides complete behavioral context, including preconditions, error cases, and return type. It references a sibling tool (view_worker_bond) for further guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description adds no parameter info, which is unnecessary given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's for reclaiming a worker reputation bond after deregistering, using a specific verb and resource. It does not explicitly differentiate from siblings like worker_register or view_worker_bond, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit conditions for successful use: cooldown passed, no open disputes, bond not slashed. It also advises checking view_worker_bond first. However, it does not list alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the amount is read from chain, can only be claimed once, and returns full collateral. Also describes the return as confirmation or error. Without annotations, this provides meaningful behavioral context, though it doesn't mention fees or other potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. It leads with the main action, then the usage condition, and ends with a clear Args section. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description provides sufficient context: the action, the condition, the return, and the argument semantics. It might be improved by explaining what happens if the contract isn't voided, but the error message mention covers this implicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section explaining job_id as 'The Voided contract ID to reclaim collateral from,' which is absent from the schema. This compensates for the 0% schema description coverage and gives the parameter practical meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Reclaim your collateral from a Voided contract as the worker (Bob)' – a specific verb and resource. Distinguishes from siblings like void_claim_requester by specifying the worker role and the eligibility condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this after a stale dispute was voided via void_dispute,' providing a clear precondition. It also indicates this is for the worker role, implying the requester should use a different tool, but it doesn't explicitly name the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description covers key behavior: irreversible on-chain action and return values. Does not specify authentication or permission details but is adequate for a simple approve action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear paragraphs and an Args section. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, and parameter meaning. Output schema exists and return values are mentioned. Complete for a simple tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (job_id) with 0% schema coverage. Description adds 'The contract ID to approve', which provides necessary context beyond the schema's title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Approve a delivered Mode B contract as the requester (Alice)', specifying verb, resource, and role. Distinguishes from siblings like dispute_delivery and submit_delivery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use instructions: after reviewing deliverable, before claiming payment. Warns that approval is irreversible and only after thorough testing. Lacks explicit mention of alternatives but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that calling before timeout will fail on chain and mentions return value (confirmation or error). Could add more about state changes or side effects, but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: purpose in first sentence, usage conditions, precondition, then Args/Returns. No unnecessary words, well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completeness is high given the simplicity: one required parameter, output schema exists, and description covers when/why/how to use, including failure condition. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (job_id) with type integer. Schema coverage is 0%, so description must add value. The description says 'The contract ID to claim from after timeout,' clarifying the schema's vague 'Job Id' tag. Adequate but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action: 'Claim funds as the worker after the review window expires without requester action.' It specifies the resource (funds), the subject (worker), and the condition (timeout), clearly distinguishing from siblings like claim_funds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: 'Use this for Mode B contracts in AwaitingApproval status where the requester has not approved or disputed within the review_window_blocks set at creation.' Also advises to check view_contract first and warns that calling before expiry will fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavior: treasury-key ownership requirement, the two eligible fund types, the one-time sweep limit, and failure for any other wallet/state. It does not explicitly mention the impact on contract state but covers the main constraints effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence, then paragraphs for conditions, args, and returns. Every sentence adds necessary context, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single-param schema, absent annotations, and presence of an output schema, the description covers the purpose, eligibility, failure conditions, parameter meaning, and return type (confirmation or error). It is complete for the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining job_id as 'The Refunded or Voided contract ID to sweep', adding the constraint that it must be a specific contract type beyond the bare integer type in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Sweep forfeited funds to the protocol treasury.' It specifies the resource (protocol treasury), the exact kinds of funds (worker's collateral from Refunded contracts, dispute fee from Voided contracts), and distinguishes from sibling tools like claim_funds or refund_contract by the treasury context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit conditions for use: only succeeds for the treasury key holder, only for specific contract states (Refunded active path, Voided), each can be swept once, and fails for any other wallet or state. This is near-explicit when-not, though it does not name alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read operation and specifies the return value (block height or error), but could explicitly state there are no side effects or that the tool is safe to call repeatedly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the purpose, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity with no parameters and an existing output schema, the description covers the usage context and return value sufficiently. It could mention that the query is non-destructive, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description does not need to explain them. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the current block height from the wallet's node, specifying the resource and action. No sibling tool performs this exact function, so it is well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this before creating a contract to choose a future expiry_block, and provides actionable guidance on computing expiry_block by adding a margin to the returned height.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden and discloses key behavioral traits: both signatures required from this wallet, cross-wallet not implemented, payment/collateral returned in the same transaction, terminal Cancelled state, and state restrictions. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured with paragraphs and clear Args/Returns labels. Every sentence adds necessary detail about behavior and limitations, though it could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers allowed states, transaction flow, current implementation limitations, and outcome. Since an output schema exists, the vague return statement is acceptable. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for job_id, but the description provides 'The contract ID to cancel,' which adds meaningful semantics. With 0% schema coverage, this compensation is sufficient for a single simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels an Active or AwaitingApproval contract by mutual agreement, with a specific verb and resource. It distinguishes from siblings like refund_contract by emphasizing mutual consent and the 'everyone made whole' aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-not-to-use context (not from Open or Disputed states) and explains the current same-wallet limitation, which guides usage. It does not name alternative tools directly, but the exclusions and conditions are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits. It details both modes, mentions off-chain delivery ('The file never touches the blockchain'), and specifies the hash generation method. This goes beyond a simple 'submit' to explain the contract flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-organized, with a clear opening sentence and structured sections for modes, off-chain note, and args. Each sentence adds value, though it is on the longer side. It is not verbose given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two modes, two parameters, integration with contract lifecycle), the description is complete. It explains the tool's purpose, covers both modes, mentions off-chain file transfer, and references sibling tools like claim_after_timeout. The output schema (confirmation/error) is noted, so no return value details needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description provides all parameter meaning. It defines 'job_id' as 'The contract ID to submit delivery for' and 'delivery_hash' as 'SHA-256 hash of your deliverable (64-char hex string)' with generation commands. This adds essential context missing from the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Submit delivery hash for an Active Idios contract as the worker (Bob).' It specifies the verb (submit), resource (delivery hash for a contract), and role (worker). It distinguishes from siblings like approve_delivery and dispute_delivery by being the initial submission step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (as worker Bob) and provides guidance on what happens in each mode (Mode A auto-settle, Mode B moves to AwaitingApproval). It mentions next steps like claim_after_timeout. However, it does not explicitly state when not to use it or contrast with other worker actions like worker_register.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the stake is slashable, that losing a dispute results in slashing, that double registration halts, and specifies asset (BEAM) and units (groth). No annotations provided, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured single paragraph that front-loads purpose and details. Slightly long but efficient; no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter, asset, consequences, and error handling. Output schema exists, so return info is handled. References sibling tool for pre-check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description explains the 'stake' parameter: it is the bond amount in groth, BEAM only. This adds meaning beyond the schema type of integer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool posts a worker reputation bond on the Idios contract, explains what the bond is, and differentiates from related tools like view_worker_bond.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (to post bond) and advises checking view_worker_bond first to avoid double registration. Could be more explicit about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behaviors: one transaction, one network fee, wallet must hold the sum plus fee, contracts are created Open, and the normal Mode B lifecycle follows. Field semantics like expiry_block and dispute_fee are also explained. However, it does not state whether batch creation is atomic or how partial failures are handled, which is a notable omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by context, constraints, and a structured field list. Every sentence adds necessary information, and the bullet-like layout improves readability. There is no filler or redundancy, making the length appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a bare-bones schema and no annotations, this description covers the essential context: purpose, usage scenarios, constraints (Mode B only, field restrictions), detailed parameter semantics, and even return value. It provides sufficient information for an agent to invoke the tool correctly despite the complexity of batch creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is minimal (only 'specs' as an empty array type, 0% description coverage), so the description must compensate. It does so thoroughly by detailing each spec field: type, required/optional status, defaults, and meaning (e.g., 'expiry_block... current + 10000 is roughly 7 days'). This fully clarifies the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear, specific action: 'Create up to 50 Mode B escrow contracts in ONE wallet transaction.' This distinctively identifies the tool's scope and batch nature. It further differentiates from siblings by stating 'Batch creation is Mode B only' and directing users to 'create_contract_b' for specs with required_collateral or spec_hash.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool: 'This is swarm payroll... locks payment for all of them at once, privately.' It also provides a clear exclusion and alternative: 'specs cannot carry required_collateral or spec_hash; create those contracts individually with create_contract_b.' This gives direct actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the behavioral disclosure burden. It explains that the dispute winner receives payment plus collateral, the fee is split among arbitrators, and the contract status remains unchanged even after claiming. It also describes the internal check of the winner_paid flag to prevent chain halting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-sentence but highly informative. Each sentence serves a purpose: stating the action, listing conditions, explaining amounts and checks, and describing the parameter. It is front-loaded with the primary action and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multiple contract states, flags, amounts) and the presence of an output schema, the description provides complete context. It covers when to call, what happens, how the flag check works, and what is returned. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, job_id, is explained as the contract ID. Despite the input schema having full type and requirement info, the description adds context by stating that only job_id is sent and that amounts are read from the chain. This adds sufficient value given low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: claiming funds from a Settled or Resolved Idios contract. It specifies the action (claim funds) and the resource (Idios contract), and distinguishes from siblings like 'claim_after_timeout' by detailing the required contract states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidelines by listing the three eligible contract statuses (Settled, ResolvedToBob, ResolvedToAlice) and explicitly states when not to use (refunded contract needs no claim). It also mentions checking the winner_paid flag via view_dispute to avoid redundant calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses auto-settlement on hash match, no human approval needed, refund/expiry behavior, collateral forfeiture, and that the function returns a confirmation or error. This gives the agent a complete picture of the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: summary, behavior explanation, usage guidance, and a numbered Args list. No sentence is wasted; the prose is tight and the parameter descriptions are concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 10-parameter creation tool with no annotations, the description provides all necessary context: what the tool does, when to use it, prerequisites, detailed parameter semantics, and return behavior. There are no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain all parameters. It does, with units (groth), defaults (subnet_id, epoch, required_collateral, spec_hash), constraints (job_id uniqueness, 64-char hex hash), and practical examples (asset_id 0/47, expiry_block = current_block + 10000). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Create a Mode A (Hash-verified settlement) Idios escrow contract.' It clearly explains what the tool does and differentiates it from Mode B (create_contract_b) by detailing the hash-verified auto-settlement mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use Mode A for deterministic outputs where the exact deliverable is agreed before the contract starts.' It also states a prerequisite (both parties must agree on result_hash). However, it does not explicitly mention when not to use this tool or name alternative tools like batch_create_contracts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description fully discloses read-only nature, no wallet funds needed, derivation from wallet and contract, and return format (hex string or error). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet informative: opens with a clear purpose, followed by explanatory context, usage note, and return description. Every sentence provides unique value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no annotations, the description fully covers what the tool does, why it exists, how it behaves, and what it returns. No gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters (100% coverage), so description adds value by explaining the semantic meaning of the returned key and its usage context, going beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves the user's Beam pubkey for the Idios contract. Distinguishes from siblings like view_contract or worker_register by specifying unique output (own pubkey).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to share with a counterparty to create contracts. Notes it is read-only and requires no funds. Could be improved by stating when not to use, but context makes alternative uses clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and excels. It states 'Read only, needs no wallet funds,' reveals that Resolved contracts remain at status 6/7 forever, and clarifies that winner_paid is the ONLY signal of payout. It also explains the bond lien semantics, giving deep behavioral context beyond a simple API note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence adds value: purpose, usage, field explanations, and parameter. It is well-structured with a field list that is easy to scan and a clear separation of ARGS. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no annotations, and an output schema (making return-value detail less critical). The description covers behavior, safety (read-only, no funds), and critical edge cases (winner_paid, bond_encumbered). It is fully self-sufficient for an agent to decide when and how to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It defines job_id as 'The contract ID whose dispute to inspect,' which clarifies that the parameter refers to the job contract, not a dispute ID. This fully disambiguates the only required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get the on chain dispute record for a Disputed or Resolved contract.' It clearly distinguishes from siblings like view_contract by focusing on the dispute record and listing dispute-specific fields. The purpose is immediately unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is given: 'Use this to follow an arbitration vote and to check payout state after resolution.' It also provides a strong when-not instruction ('Never retry claim_funds when winner_paid is 1'), which indirectly differentiates from the claim_funds sibling. However, it does not explicitly name alternative tools for non-dispute queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description explicitly states 'Read only, needs no wallet funds,' and thoroughly explains each returned field and its meaning. This fully discloses the behavioral traits of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, usage, field details, note on read-only, and args. Every sentence adds value, and there is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, no nested objects) and the presence of an output schema, the description fully covers purpose, usage, parameters, and output fields with clear explanations of each field's meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only a title for 'worker_pk' and a default empty string, providing no meaning. The description adds crucial semantics: 'Optional worker pubkey hex. Defaults to your own key,' fully compensating for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('check') and resource ('worker's reputation bond on the Idios contract'). It clearly distinguishes from sibling tools like view_worker_reputation by focusing on the bond aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'With no argument, shows your own bond' and 'Pass a counterparty's worker pubkey to check theirs before creating a contract.' It explains the purpose of checking before contracting but does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: combines two signals, not a global score, suggests collateral via a transparent heuristic. Explains the reasoning behind the suggestion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured: starts with purpose, then details signals, then parameter explanation. Each sentence adds value; no fluff. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage and no annotations, the description fully covers input, behavior, and output (mentions JSON worker card). It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds full meaning: worker_pk defaults to own key, payment is optional in groth and triggers collateral suggestion. This compensates completely for lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a 'worker card' with reputation info combining on-chain bond and observed history. It distinguishes from siblings (view_contract, view_dispute) by focusing on worker reputation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (before hiring a worker) and what it provides (suggested collateral). It doesn't explicitly state when not to use, but the context and sibling tools make it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully discloses behavior: permissionless call, failure on boundary block, status change to Voided, fund distribution (each side reclaims principal, forfeited dispute fee), and that the call fails if timeout not yet passed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but each sentence serves a purpose, structured into logical paragraphs (purpose, condition, consequences, prerequisites). Could be slightly more concise but maintains clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers entry conditions, side effects, and subsequent steps. No significant gaps remain for a complex transaction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds crucial meaning: 'The Disputed contract ID to void.' This clarifies the parameter's role, though additional constraints (e.g., format) are absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (void a disputed contract), the specific condition (arbitrator never resolved), and differentiates from sibling tools like void_claim_requester by explaining the recovery path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (stale dispute after timeout), the strict block height condition, that it's permissionless, and the need to check view_contract and get_chain_info beforehand. Warns against assuming timeout values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It explains exactly what happens to the requester's payment, what happens to the worker's collateral (forfeited to treasury, not to requester), and that funds are returned in the refund transaction itself. These are non-obvious state-changing behaviors disclosed clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: purpose, valid conditions, effects, exclusions, and argument/return summary. Despite its length, every sentence contributes meaningful behavioral or usage information, and the formatting with bullets and clear paragraphs enhances scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has complex state-transition logic involving expiry, collateral forfeiture, and exclusion windows. The description covers all relevant scenarios, the return behavior, and the error conditions. Even though an output schema exists, the description explicitly states that it returns a confirmation or error, which is adequate for a refund action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides 'job_id' as an integer with title 'Job Id'. The description adds 'The contract ID to refund,' which is minimal but sufficient for a single parameter. Given the low schema coverage, the description compensates by at least indicating the semantic role of the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Refund an expired Idios contract as the requester (Alice).' This clearly identifies the tool's role and actor, and the detailed lifecycle conditions distinguish it from siblings like mutual_cancel, claim_funds, and dispute_delivery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly enumerates the two valid situations, requires expiry_block to have passed, and states when refund is not possible (after delivery submission). It also names alternatives ('use approve, dispute, or the dispute resolution flow instead'), making the when-to-use decision unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for transparency. It discloses the cooldown, the need for a subsequent reclaim, the unbonded status, and that disputes can still slash the bond, which are critical behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured and front-loaded: a clear purpose statement, then the cooldown timing, then implications, then return value. Every sentence contributes essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no parameters, the description covers the entire workflow and potential risks (cooldown, reclaim, dispute encumbrance), providing complete context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema is trivially empty. The description correctly makes no parameter claims and the baseline for 0 params is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific action ('Start withdrawing your worker reputation bond') and elaborates with the cooldown and reclaim flow, distinguishing it from sibling tools like worker_register and worker_reclaim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the cooldown duration, instructs to call worker_reclaim afterward, and warns about being unbonded for new work, giving clear context for when to use this tool and how it fits the lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that collateral is locked, contract moves to Active status, asset type is read from chain, and disputes may forfeit collateral. These are critical behavioral traits beyond basic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and uses a clear Args section. Every sentence earns its place, providing essential warnings without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters and the description covers prerequisites, state changes, risk warnings, and return behavior. No output schema details needed since description mentions confirmation/error. Complete for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions, so the description fully compensates by defining job_id as the contract ID and collateral as 'Amount in groth to lock as collateral' with typical value and dispute consequence. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Commit collateral to an Open Idios contract as the worker (Bob).' It uses a specific verb and resource, and the worker role distinguishes it from requester-side actions like create_contract_a or submit_delivery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites ('You must be the worker whose pubkey was used to create the contract') and clear when-not-to-use guidance ('Check the contract's expiry_block... Do not commit unless the remaining time is enough to deliver'). Also notes the consequence of forfeiture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden and excels. It discloses key behaviors: locks payment from wallet, worker must commit collateral, timeout review allows worker claim, expiry_block causes collateral forfeiture if no delivery, dispute_fee is non-refundable, and returns confirmation/error. These details go far beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence is value-dense. It is well-structured: main purpose, lifecycle, usage guidance, then parameter list. Front-loaded with the core action and decision-relevant information. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema given, the description is remarkably complete. It covers the entire contract lifecycle, timeout behavior, collateral forfeiture, dispute handling, and return values. It also ties into sibling tools (commit_collateral, claim_after_timeout) and gives practical block-height estimates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 comprehensively. Every parameter is explained with units, valid values, defaults, and purpose: payment in groth, asset_id 0/47, expiry_block estimated in days, review_window_blocks conversion, dispute_fee implications, required_collateral floor, optional spec_hash. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a Mode B (Reviewed settlement) Idios escrow contract' – a specific verb (create) plus resource (Mode B escrow contract). It clearly distinguishes from siblings by detailing the review workflow and explicitly recommending Mode B for work requiring human/agent judgment, unlike other contract types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use case: 'Use Mode B for any work where a human or agent needs to judge the output: custom AI agents, automation pipelines, consulting, data labelling, model fine-tuning where exact output hash is not known in advance.' This implies when not to use (e.g., when output hash is known, likely Mode A). It also outlines the complete workflow and prerequisites (worker must call commit_collateral).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses critical behaviors: 'nothing on chain and no wallet involvement', and warns that listings are 'UNTRUSTED MARKETPLACE LISTINGS' wrapped in an envelope, with fields sanitised and length capped. It also notes the output is data, never instructions. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although longer than two sentences, every sentence earns its place: purpose, workflow, safety, untrusted envelope, parameter explanation, and return value. The structure is logical with clear paragraphs, and no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (off-chain workflow, untrusted data, no wallet), the description is complete. It explains the output (JSON inside untrusted envelope, or message), the filtering behavior, safety, and next steps, without relying on an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'skill' with zero schema coverage. The description fully compensates by explaining: 'Optional case insensitive filter matched against each job's title, skills needed, and description.' This gives complete semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Discover open job postings on the Idios marketplace to work on' and explicitly frames it as 'The requester side mirror of find_workers'. This clearly distinguishes it from the sibling tool find_workers and states the purpose unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow context: workers should agree terms off chain, share their pubkey (get_key), consider registering a bond (worker_register), and explains that this is a plain HTTPS fetch with no wallet involvement. It names alternative/related tools and makes clear when to use this tool (worker seeking work).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses that this is a plain HTTPS fetch with no chain/wallet involvement, that results arrive in an 'UNTRUSTED MARKETPLACE LISTINGS' envelope where contents are data not instructions, that fields are sanitized/length-capped, and that the Bonded flag is operator-reviewed rather than chain truth. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: purpose, workflow, safety warning, and parameter semantics. It is front-loaded with the key function and uses numbered steps and an Args block, making it scannable despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a discovery tool with two optional params and an output schema, the description covers candidate selection, the verification workflow, security caveats, and return shape ('matching listings as JSON inside the untrusted envelope, or a message if none match'). No important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the Args section fully compensates by explaining skill as a 'case insensitive filter matched against each worker's name, skills, and description' and bonded_only as filtering to listings carrying the Bonded flag. This adds real meaning beyond the bare schema defaults and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Discover workers on the Idios marketplace to hire for a contract' and explicitly states it 'Fetches the public worker listings.' It clearly differentiates from sibling tools by framing the result as candidate discovery for a hiring workflow, distinct from registration, contract creation, and verification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit numbered workflow: call this to find candidates, then verify via view_worker_bond, optionally view_worker_reputation, and finally create_contract_b. This gives clear when-to-use guidance and names the alternative follow-on tools, exceeding the basic 'use this for X' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/honeytones/idios'
If you have feedback or need assistance with the MCP directory API, please join our Discord server