Open Agreements

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds value by disclosing the return modes (url or mcp_resource) and the redline generation behavior for field-selector templates. It does not mention whether the original template is modified, but the tool creates new documents, which aligns with non-destructive nature. 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 extremely concise with only two sentences. The first sentence covers the core purpose and return options, and the second adds the special redline behavior. No unnecessary words, every sentence earns its place.

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

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

The description explains the main functionality and the redline feature, but it assumes domain knowledge of 'field-selector templates' without defining them. It also does not describe return values since there is no output schema. For a complex tool with multiple parameters, it is mostly complete but could include a brief definition of field-selector templates.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds significant value beyond the schema by explaining the redline_base options (source vs clean) and that include_redline defaults to true for field-selectors. It also contextualizes return_mode and the template ID format.

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 fills a legal agreement template with field values and returns a document via URL or MCP resource. It also distinguishes behavior for field-selector templates by generating a redline document. This differentiates it from siblings like get_template (retrieves template details) and list_templates (lists templates).

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 for filling templates but does not explicitly state when to use this tool versus alternatives. It provides no guidance on prerequisites, when not to use it, or how it relates to sibling tools. The purpose is clear, but usage context is implied rather than stated.

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

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

Annotations declare readOnlyHint=true; description adds valuable behavioral context that it returns 'full field metadata' (indicating richness of response) without contradicting safety hints.

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

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

Single efficient sentence with zero waste. Front-loaded action verb with precise qualifiers ('single', 'full field metadata') that convey scope and response content.

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?

Adequate for a simple read-only retrieval tool with one required parameter. Mentions field metadata to compensate for missing output schema. No critical gaps given tool complexity.

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 has 100% description coverage with example value; description does not add parameter-specific semantics but meets baseline expectation when schema documentation 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?

Excellent specificity: verb 'Fetch', resource 'template definition', scope 'single' distinguishes from sibling list_templates/search_templates, and 'definition' distinguishes from fill_template which likely populates data.

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

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

Implies usage through 'single' (suggests use when you have a specific ID) but lacks explicit when-to-use guidance contrasting with list_templates or search_templates siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds concrete behaviors: paginated results, compact catalog, stable lexicographic order by template_id, and clarifies that it returns lightweight metadata.

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

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

Three sentences are concise and front-loaded: first sentence states purpose, second gives alternative for detail, third mentions ordering and alternative search. No wasted words.

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

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

Covers pagination, ordering, and sibling differentiation. Lacks specification of what fields the lightweight metadata includes, but given the tool's role as a catalog for discovery, the information provided 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 coverage is 100% with descriptions for both parameters (limit and cursor). The description does not add extra meaning beyond what the schema provides.

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

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

The description clearly states the tool lists all available legal agreement templates as a paginated compact catalog. It distinguishes from siblings by directing users to get_template for full detail and search_templates for topic/jurisdiction/source filtering.

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

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

Explicitly provides when-to-use guidance and names alternatives: 'call get_template for full per-field detail' and 'use search_templates instead' for specific searches.

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

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

Annotations declare readOnlyHint=true. Description adds valuable behavioral context: BM25 ranking algorithm and specific fields searched across. Does not mention return structure or rate limits, but safety profile is covered 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?

Three sentences, zero waste. Front-loaded with core purpose, followed by mechanism (BM25), search scope, and sibling differentiation. Every clause earns its place.

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

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

Given 100% schema coverage, readOnly annotations, and the tool's straightforward search purpose, the description is functionally complete. Minor gap: no hint at return value structure, though this is partially mitigated by the tool name and sibling get_template.

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

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

Schema coverage is 100% with detailed descriptions and examples for all 4 parameters. Description mentions 'by keyword' (aligning with query param) and implies filtering via the search scope, but does not add semantic detail beyond what the comprehensive schema already provides. Baseline 3 appropriate 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?

States specific verb (search), resource (legal agreement templates), ranking method (BM25), and exact search scope (names, descriptions, categories, sources, field definitions). Clearly distinguishes from list_templates sibling.

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

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

Explicitly states when to use this tool vs the sibling alternative: 'Use this instead of list_templates when you know what kind of agreement you need.' Provides clear selection criteria.

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