Ambr

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

Annotations indicate non-readOnly, non-destructive, and idempotent, which the description aligns with by describing a handshake initiation (non-read) that is auditable and requires approval. The description adds valuable context beyond annotations: it clarifies that the action records intent, requires principal approval, and is auditable with delegation scope and identity. However, it doesn't detail rate limits or error behaviors, keeping it from a perfect score.

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 well-structured with clear sections (purpose, requirements, args, returns, legibility) and front-loaded key information. It avoids redundancy, but the Args section slightly repeats schema details, and the legibility note could be more integrated. Overall, it's efficient with most sentences earning their place.

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

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

Given the tool's complexity (involves delegation, approval, and auditing) and lack of output schema, the description is mostly complete. It covers purpose, prerequisites, parameters, returns, and legibility. However, it doesn't fully explain the return values ('Handshake status and next steps') or potential errors, leaving minor gaps for an agent to infer.

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 all parameters thoroughly. The description adds minimal semantic value beyond the schema—it briefly mentions parameters in the Args section but doesn't provide additional context like examples or edge cases. This meets the baseline of 3 since the schema does the heavy lifting.

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 specific verbs ('Initiate a handshake on a contract') and distinguishes it from siblings like ambr_create_contract (creates contracts) or ambr_get_contract (reads contracts). It specifies acting 'on behalf of your delegating principal' and recording 'intent to accept, reject, or request changes,' making the purpose unambiguous and distinct.

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

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

The description explicitly states when to use this tool: 'Requires an API key with an active delegation' and 'The principal must separately approve via wallet signature.' It also implies when not to use it by distinguishing from siblings—e.g., use ambr_get_contract for reading, not this for handshake initiation. This provides clear context and prerequisites.

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: it explains the dual-format nature (human-readable + JSON), storage location (Ambr/Reader Portal), authentication requirements (API key with credits), and the legibility guarantee. While annotations cover basic safety (non-destructive, non-idempotent), the description provides richer operational context without contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with clear sections: purpose statement, behavioral context, prerequisites, usage guidance, parameter explanations, return values, and legibility guarantee. Every sentence adds value with zero wasted words, and key information is front-loaded.

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

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

For a complex contract-creation tool with 5 parameters, nested objects, and no output schema, the description provides comprehensive context: it explains the tool's purpose, behavioral characteristics, authentication requirements, parameter semantics, return values, and sibling tool relationships. The legibility guarantee section adds important architectural context.

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

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

With 60% schema description coverage, the description compensates well by explaining the purpose of key parameters: template slug comes from ambr_list_templates, parameters are template-specific, and principal_declaration structure is clarified. It also explains optional parameters' purposes (parent_contract_hash for amendments, amendment_type options), adding meaningful context beyond the schema.

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

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

The description clearly states the specific action ('Generate a Ricardian Contract from a template') and distinguishes it from siblings by mentioning dual-format output and storage on Ambr. It explicitly names a sibling tool (ambr_list_templates) for discovering templates, showing clear differentiation.

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

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

The description provides explicit guidance on when to use this tool: 'Use ambr_list_templates first to discover templates and their required parameters.' It also mentions prerequisites (API key with credits) and distinguishes from sibling tools by specifying its unique contract-creation function.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior, but the description adds valuable context beyond that: it explains the authentication-dependent response (full contract vs. metadata-only), mentions the dual-format pairing (prose and JSON), and notes that retrieval preserves hash consistency. This enhances understanding without contradicting 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 well-structured and front-loaded with the core purpose. Each sentence adds value: authentication behavior, lookup formats, parameter explanation, return details, and legibility note. There's no wasted text, and it efficiently conveys necessary information.

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

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

Given the complexity (authentication-dependent responses, multiple lookup formats) and lack of output schema, the description does a good job explaining what to expect. It covers return types (full contract vs. metadata) and behavioral notes like hash preservation. A slight gap is the absence of explicit error handling or rate limit mentions, but it's largely 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 input schema already fully documents the 'id' parameter. The description repeats the same information about ID formats without adding new syntax or format details beyond what's in the schema. This meets 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 specific action ('Retrieve a contract') and distinguishes it from siblings like ambr_get_contract_status (which only gets status) and ambr_create_contract (which creates rather than retrieves). It explicitly lists the three lookup formats, making the purpose unambiguous.

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

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

The description provides clear context about when to use it (to retrieve contracts by ID, hash, or UUID) and implies alternatives by mentioning authentication-dependent behavior. However, it doesn't explicitly state when to use ambr_get_contract_status instead, which would be helpful for sibling differentiation.

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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), but the description adds valuable context beyond this: it explains that amendments are 'bilateral and themselves dual-format' and that 'the chain stays legible from original through every revision,' which clarifies how amendment data is structured and maintained. This enhances understanding without contradicting 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 well-structured and appropriately sized, with a clear purpose statement upfront, followed by usage context, parameter details, return values, and additional legibility notes. Most sentences earn their place by adding useful information, though the 'Legibility' sentence could be slightly more concise. Overall, it is efficient and front-loaded.

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

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

Given the tool's moderate complexity (single parameter, no output schema), the description is fairly complete: it covers purpose, usage, parameters, return values, and amendment behavior. However, it lacks details on error handling or specific status values (e.g., what 'active' means), which could be helpful. With annotations providing safety info, it is mostly adequate but has minor gaps.

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

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

Schema description coverage is 100%, so the input schema fully documents the single parameter 'id' with its description. The description repeats the parameter info in the 'Args' section but does not add significant meaning beyond what the schema provides, such as examples or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the description adds minimal extra value.

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 specific verbs ('check the status', 'returns') and resources ('contract and its amendment chain'), distinguishing it from siblings like ambr_get_contract (which likely retrieves full details) and ambr_verify_hash (which focuses on hash verification). It explicitly mentions what it returns, making the purpose distinct and well-defined.

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 on when to use this tool ('useful for verifying if a contract is active, amended, or terminated'), but it does not explicitly state when not to use it or name alternatives among siblings. While it implies differentiation from other tools by focusing on status and amendments, it lacks explicit exclusions or comparisons.

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 cover key traits (read-only, non-destructive, idempotent, closed-world), but the description adds valuable context beyond that: it states 'No authentication required' (auth needs) and explains the return format in detail. It also provides conceptual context about templates being 'parameter schema for dual-format contracts' and benefits like 'keeps your request conformant'. 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 well-structured and front-loaded with the core purpose, followed by usage guidance, authentication info, return details, and conceptual notes. Every sentence adds value without redundancy, making it efficient 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 simplicity (0 parameters, no output schema), the description is complete: it covers purpose, usage, behavioral traits (including auth), return format, and conceptual rationale. With annotations providing structured safety info, the description fills all necessary gaps for effective agent use.

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

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

With 0 parameters and 100% schema description coverage, the baseline is high. The description compensates by explaining the absence of parameters implicitly (it's a simple list operation) and adds semantic context about what the tool does without inputs, which is appropriate for a parameterless tool.

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

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

The description clearly states the verb ('List') and resource ('available contract templates on Ambr'), specifying it returns 'all active Ricardian Contract templates' with detailed fields. It explicitly distinguishes from sibling tools by mentioning 'before creating a contract with ambr_create_contract', making the purpose 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 explicit guidance on when to use this tool: 'Use this to discover which templates are available before creating a contract with ambr_create_contract.' This directly names the alternative sibling tool and gives a clear context for usage, with no misleading or missing exclusions.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable context about what verification means ('matching hash means the prose a human reads and the JSON a machine parses are the same document that was originally signed') and explains the significance of the operation beyond the basic safety profile indicated by 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 well-structured with clear sections (purpose, args, returns, conceptual note) and appropriately sized. The 'Legibility' paragraph adds conceptual value but could be considered slightly extraneous for pure tool selection. Most sentences earn their place in explaining the tool's function.

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

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

For a single-parameter verification tool with comprehensive annotations and no output schema, the description provides good completeness. It explains what verification accomplishes, documents the return structure, and adds conceptual context. The main gap is the lack of an output schema, but the description compensates by documenting return values.

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

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

Schema description coverage is 100%, with the schema already documenting the single required hash parameter as 'SHA-256 hash to verify (64-character hex)'. The description repeats this information in the Args section but doesn't add meaningful semantic context beyond what the schema provides. Baseline 3 is appropriate when schema coverage is complete.

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 ('verify a contract's SHA-256 hash') and resource ('contract stored on Ambr'), distinguishing it from siblings like create_contract or get_contract. It explicitly mentions document integrity verification, which is a distinct purpose from other contract operations.

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 ('to confirm document integrity'), but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools. The context is sufficient for understanding the primary use case without explicit exclusions.

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