Hashlock — Intent Trading Protocol

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

Annotations cover basic traits (non-readOnly, openWorld, non-idempotent, non-destructive). The description adds valuable context about privacy controls ('hide amounts, identity, or run a fully private OTC deal') and the sealed-bid commitment nature, but does not disclose operational details like rate limits, authentication needs, or what 'commit' entails beyond submission.

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: first states purpose and key features, second lists use cases. Every phrase adds value—no repetition or fluff. Efficiently front-loaded with core functionality.

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 5 parameters, no output schema, and annotations covering basic traits, the description is reasonably complete for a submission tool. It explains the tool's role in privacy-focused trading but lacks details on response format, error conditions, or confirmation of commitment success.

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 parameters are fully documented in the schema. The description mentions hiding amounts and identity, which aligns with hideAmounts and hideIdentity parameters, but adds no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Submit a sealed-bid commitment for a trading intent') and resource ('Hashlock protocol'), distinguishing it from siblings like create_intent (which creates) or explain_intent (which explains). It explicitly mentions the protocol context (hashlock.ai).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('peer-to-peer trading, private negotiations, agent-to-agent settlement, and dark pool orders'), but does not explicitly state when NOT to use it or name specific alternatives among the sibling tools (e.g., vs. hashlock_create_intent).

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 cover key traits (non-read-only, open-world, non-idempotent, non-destructive), so the bar is lower. The description adds context about privacy levels, KYC tiers, and settlement terms, which are useful behavioral details not in annotations. However, it lacks information on rate limits, authentication needs, or error handling, limiting its transparency.

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 front-loaded with the core purpose and scope in the first sentence, followed by additional context. It is appropriately sized for a complex tool, but could be slightly more concise by avoiding repetition (e.g., listing asset types in detail). Overall, it is efficient with minimal waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity (34 parameters, no output schema) and rich annotations, the description provides adequate context on what the tool does and its scope. However, it lacks details on return values, error cases, or operational constraints, making it incomplete for full agent understanding without additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 34 parameters. The description mentions general categories (e.g., 'what you give, what you want, privacy level, KYC tier, and settlement terms') but does not add specific semantic details beyond what the schema provides, aligning with the baseline for high coverage.

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 explicitly states the action ('Create a trading intent') and specifies the scope ('to swap, buy, sell, exchange, or convert any asset'). It distinguishes from siblings by focusing on creation rather than commitment, explanation, parsing, or validation, making the purpose highly specific and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: for creating trading intents across various assets and blockchains, with support for different user types. However, it does not explicitly mention when not to use it or name alternatives (e.g., using sibling tools for other operations), leaving some guidance implicit.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds context about the explanation output (plain-language, covering specific aspects like privacy/KYC), which is useful but not rich behavioral detail beyond annotations. 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?

The description is a single, efficient sentence that front-loads the purpose and details without waste. Every part earns its place by specifying the action, resource, and key aspects explained.

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 one parameter with full schema coverage and annotations covering safety/idempotency, the description is mostly complete. However, no output schema exists, and the description does not detail return values (e.g., format of explanation), leaving a minor gap for a tool that outputs explanations.

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 one parameter ('intent' as a JSON string), so the schema fully documents the parameter. The description does not add meaning beyond the schema, such as format examples or constraints, but baseline is 3 when schema coverage is high.

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 specific action ('Get a plain-language explanation') and the resource ('trading intent'), with detailed scope covering crypto/tokens/assets, amounts, blockchain, privacy, and KYC settings. It distinguishes from siblings like hashlock_commit_intent (which commits) and hashlock_create_intent (which creates).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying 'trading intent' and what aspects are explained, but does not explicitly state when to use this tool versus alternatives like hashlock_parse_natural_language or hashlock_validate_intent. It provides clear context but lacks explicit exclusions or named 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about language support (English and Turkish) and the types of trading phrases it understands, which goes beyond what annotations provide. 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?

The description is efficiently structured with protocol context, core function, specific examples, and language support in just two sentences. Every element adds value 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 tool's complexity (natural language parsing), rich annotations, and 100% schema coverage, the description is mostly complete. It explains what the tool does and provides examples, though without an output schema, it doesn't describe return values. For a parsing tool with good annotations, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add additional meaning about the parameters beyond what's in the schema, but the baseline is 3 when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: converting natural language into structured trading intent with specific examples ('sell 10 ETH for USDC above 4000', 'buy tokenized real estate with 50k DAI', etc.). It distinguishes from siblings by focusing on parsing rather than committing, creating, explaining, or validating intents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (converting everyday language into structured trading intent) and mentions support for English and Turkish. However, it doesn't explicitly state when not to use it or name specific alternatives among the sibling tools.

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?

The description adds valuable behavioral context beyond annotations by specifying what the validation checks (missing fields, invalid token amounts, chain mismatches, business rule violations). Annotations already indicate it's read-only, non-destructive, idempotent, and open-world, but the description clarifies the validation scope, which is helpful for agent decision-making.

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 front-loaded and concise, with two sentences that efficiently convey purpose and usage guidelines without unnecessary details. Every sentence adds value, making it well-structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (validation with multiple checks), annotations cover safety aspects, but there is no output schema. The description adequately explains what validation entails, though it could benefit from mentioning potential outcomes (e.g., error messages or success indicators) to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter 'intent' as 'The intent JSON to process'. The description adds no additional parameter details beyond this, such as format examples or constraints, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('validate') and resource ('crypto trading intent'), and distinguishes it from siblings by mentioning what it catches (missing fields, invalid token amounts, etc.). It explicitly contrasts with 'commit' operations, which helps differentiate from tools like hashlock_commit_intent.

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 ('always validate before committing') and implies alternatives by referencing 'committing' (likely hashlock_commit_intent). This gives clear context for usage versus other tools in the workflow.

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