openregistry

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

The description adds substantial behavioral context beyond annotations: it explains the two response shapes (embedded vs resource_link), details workflow steps for oversized documents, provides critical rules about citation practices and error handling, describes caching behavior and auto-resolution mechanisms, and explains jurisdiction-specific considerations. While annotations cover basic safety (readOnlyHint, idempotentHint), the description adds rich operational context.

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

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

The description is well-structured with clear sections (Response Shapes, Workflow, Critical Rules) and uses bullet points effectively. While comprehensive, it maintains focus on essential information - every sentence serves a clear purpose in guiding tool usage. The front-loaded statement about being the 'Primary tool for reading a filing's content' immediately establishes purpose.

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 (9 parameters, no output schema), the description provides exceptional completeness: it covers response formats, error handling, workflow integration with sibling tools, jurisdiction considerations, caching behavior, and practical usage constraints. The description fully compensates for the lack of output schema by detailing what the tool returns and how to interpret different response types.

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 89% schema description coverage, the baseline would be 3, but the description adds meaningful context about parameter usage: it explains the primary use of document_id (from list_filings/get_financials), clarifies that override parameters are for 'rare use' cases, provides practical guidance on format selection ('recommended — XHTML > XML > JSON > PDF'), and explains the practical implications of max_bytes settings. This adds significant value beyond the schema descriptions.

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

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

The description explicitly states this is the 'Primary tool for reading a filing's content' and distinguishes it from sibling tools by explaining that filing metadata alone is insufficient - the actual content requires this tool. It clearly identifies the verb (reading/fetching) and resource (filing documents).

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 comprehensive usage guidance: it specifies when to use this tool ('MANDATORY for any substantive answer'), explains the workflow for different response types, distinguishes when to use sibling tools like 'fetch_document_pages' and 'get_document_navigation', and explicitly states when NOT to use certain approaches ('Don't reflexively retry with a larger max_bytes').

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 the annotations. While annotations declare read-only, non-destructive, and idempotent operations, the description details the return structure (unified fields plus jurisdiction_data), explains status field semantics, describes caching behavior ('fresh: true bypasses the cache'), and mentions performance implications of optional flags ('slower', 'doubles upstream calls'). No contradictions with annotations are present.

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 efficiently packed with information. It front-loads the core purpose, then details return values, exclusions, input guidance, optional flags, and per-country caveats. While comprehensive, some sentences are lengthy, and the density of information might slightly reduce immediate clarity, though every sentence adds value.

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

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

Given the tool's complexity (6 parameters, no output schema, rich annotations), the description is largely complete. It covers purpose, usage, return structure, exclusions, input guidance, and jurisdictional nuances. However, without an output schema, it could more explicitly detail the full return format or error conditions, though the annotations provide safety 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 100% schema description coverage, the baseline is 3. The description adds meaningful context beyond the schema: it explains the variability of company_id formats, provides guidance on obtaining company_id from 'search_companies', clarifies that optional flags are jurisdiction-specific and ignored elsewhere, and explains the purpose of the fresh parameter. However, it doesn't fully detail all parameter interactions or edge cases.

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: 'Fetch the full profile of a company by its registry-specific ID.' It specifies the verb ('fetch'), resource ('company profile'), and key identifier ('registry-specific ID'), and distinguishes it from siblings by explicitly listing what it does NOT include (filings, officers, etc.) and naming alternative tools for those purposes.

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 versus alternatives. It states what the tool does NOT include and names specific sibling tools for those purposes (e.g., 'list_filings', 'get_officers'). It also advises pulling company_id from 'search_companies' rather than guessing, and directs users to 'list_jurisdictions' for per-country details.

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, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it explains error conditions (404/502 for synthesized IDs, 501 for paywalled/unsupported jurisdictions), availability caveats (available_formats may be empty), and the purpose of checking metadata before downloading large documents. 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 clear paragraphs: first states purpose and returns, second provides usage guidance, third gives critical warnings, and fourth covers edge cases. Every sentence adds value without redundancy, and key points are front-loaded (e.g., the warning about not constructing IDs is emphasized).

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 (metadata retrieval with jurisdiction-specific behaviors), the description is highly complete. It covers purpose, usage, prerequisites, error cases, and relationships to other tools. While there's no output schema, the description details return values (formats, sizes, page count, etc.). The annotations provide safety context, and the description fills in behavioral nuances adequately.

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 67% (2 of 3 parameters have descriptions). The description adds meaningful context for document_id beyond the schema's 'Document ID from a previous list_filings call' by warning against constructing IDs and explaining composite ID formats. It also clarifies jurisdiction usage by referencing list_jurisdictions for details. However, it doesn't explicitly address the 'fresh' parameter's semantics.

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 metadata') and resource ('filing document'), distinguishing it from sibling tools like fetch_document (which downloads content) and list_filings (which lists documents). It explicitly mentions what metadata is returned (content formats, byte sizes, page count, source URL, creation date, jurisdiction_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?

The description provides explicit guidance on when to use this tool ('call this before fetch_document when the document might be large or you don't yet know the format') and when not to use it ('do NOT construct or guess document_id values'). It names specific alternatives (list_filings for obtaining IDs, fetch_document for downloading, list_jurisdictions for jurisdiction details).

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, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context: navigation aids may be truncated, contain OCR errors, or have false positives, and it explains the caching requirement and the 'fresh' parameter's effect. 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 with clear sections: purpose, returns, critical warnings, and prerequisites. It's front-loaded with key information, though it could be slightly more concise by integrating some details (e.g., jurisdiction support) more tightly. Every sentence adds value, but minor redundancy exists.

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 (navigation for large documents) and lack of output schema, the description is mostly complete: it explains purpose, usage, behavioral caveats, and prerequisites. However, it doesn't detail the exact structure of returned navigation data (e.g., format of outlines or landmarks), which could aid agent interpretation. Annotations cover safety aspects well.

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 80%, so the schema documents most parameters well. The description adds context for 'jurisdiction' by mentioning it's for official government sources and referencing 'list_jurisdictions' for details, but doesn't explain other parameters like 'document_id' or 'fresh' beyond what the schema provides. Baseline 3 is appropriate given 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: 'Open the navigation index for a cached document' and specifies it returns 'outline (PDF bookmarks), per-page text previews, keyword-matched landmarks, text_layer classification, and source URLs.' It distinguishes from siblings like 'fetch_document_pages' by emphasizing this is for navigation aids only, not authoritative content.

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 usage guidelines: call this FIRST for large PDFs or when locating sections, NEVER cite navigation aids as source material, and always follow up with 'fetch_document_pages' for authoritative content. It also specifies prerequisites: requires cached document bytes and to call 'fetch_document' first for new documents, clearly differentiating from 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?

The description adds significant behavioral context beyond annotations: it explains GDPR masking, jurisdiction-specific limitations (e.g., birth-date precision, 501 gating), cache bypass with 'fresh: true', and how flags are ignored on unsupported registries. While annotations cover read-only, open-world, and idempotent hints, the description enriches this with practical constraints and data source details 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 core functionality, followed by details on data shape, flags, and caveats. While comprehensive, it remains focused with minimal redundancy, though some sentences could be slightly tightened (e.g., the per-country caveats paragraph is dense but informative).

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 (5 parameters, no output schema, rich annotations), the description is highly complete: it covers purpose, usage, data format, parameter semantics, jurisdiction-specific behaviors, and links to other tools for further details. It addresses gaps from missing output schema by describing the unified shape of returned officers and potential errors like 501.

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 schema description coverage at 60%, the description compensates by explaining parameter implications in detail: it clarifies the default and effect of 'include_resigned', specifies that 'group_by_person' is for CZ only, and notes that 'fresh' bypasses cache. It also adds context for 'jurisdiction' and 'company_id' by linking to other tools for support details, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Return the officers of a company' with specific details about what constitutes an officer (directors, secretaries, members, etc.) and distinguishes it from sibling tools like 'get_officer_appointments' by explaining the relationship between them. It goes beyond a simple list to explain the unified shape of returned data and cross-company tracing capabilities.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: it mentions using 'get_officer_appointments' for cross-company tracing with officer_id, and directs users to 'list_jurisdictions' for per-country caveats and support details. It also explains when certain flags are applicable (e.g., 'group_by_person' for CZ only) and when jurisdictions return 501 errors.

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 read-only, open-world, idempotent, and non-destructive hints. The description adds valuable context beyond annotations: it explains that responses may vary by jurisdiction (e.g., empty lists for joint-stock companies, structured arrays or document pointers), includes disclosure flags, mentions caching behavior with `fresh: true`, and notes that unsupported jurisdictions return 501. It also references per-country caveats and how to access them via other tools, though it doesn't detail rate limits or auth needs.

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 (e.g., 'When to call this tool,' public disclosure details, per-country caveats) and uses bold for emphasis. It is appropriately sized for the tool's complexity, though some sentences are lengthy. Every sentence adds value, such as explaining jurisdictional variations and tool interactions, with minimal 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 (legal-registry data with jurisdictional variations), no output schema, and rich annotations, the description is highly complete. It covers purpose, usage guidelines, behavioral nuances (e.g., response shapes, caching, error codes), parameter context, and references to other tools for further details. It adequately compensates for the lack of output schema by describing possible response types and flags.

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 low (33%), with only the 'jurisdiction' parameter described in the schema. The description compensates by explaining the purpose of 'fresh' (bypasses cache) and implying 'company_id' identifies the target company. It also adds context about jurisdiction codes (ISO 3166-1 alpha-2) and references `list_jurisdictions` for details, though it doesn't fully document all parameter formats or constraints beyond what's implied.

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 returns 'the shareholders / members / quota-holders of a company' from the 'legal-statutory equity roster published by the company registry,' with explicit scope ('no ownership-threshold filter'). It distinguishes from sibling `get_persons_with_significant_control` by explaining the different registers and concepts, making the purpose specific and well-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 (e.g., for 'shareholders', 'members', 'quota-holders' in various languages) and when not to use it (e.g., not for PSC/beneficial owners unless explicitly asked). It names the alternative tool (`get_persons_with_significant_control`) and explains the conceptual differences, including examples of disagreement between registers.

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 substantial behavioral context beyond what annotations provide. While annotations declare readOnlyHint=true, idempotentHint=true, etc., the description details pagination behavior (limit default 25, max 1000, cursor vs offset pagination), jurisdiction limitations (unsupported jurisdictions return 501), document availability constraints (has_document flag, paywalled bodies), and sorting order (newest-first). This provides crucial operational context that annotations don't cover.

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 for a complex tool with 7 parameters. It's front-loaded with core functionality, then addresses filtering, pagination, and jurisdiction caveats. While comprehensive, every sentence earns its place by providing necessary operational context. Minor deduction for some density, but overall efficient.

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 (7 parameters, jurisdiction variations, pagination differences) and lack of output schema, the description provides excellent completeness. It covers return format, filtering options, pagination mechanisms, jurisdiction limitations, error conditions, and relationships to sibling tools. The guidance to call list_jurisdictions for per-country details appropriately delegates complexity while maintaining completeness.

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

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

With 86% schema description coverage, the baseline would be 3, but the description adds significant value beyond the schema. It explains the relationship between category filtering and jurisdiction-specific codes, clarifies pagination behavior (cursor vs offset by jurisdiction), and provides context about company_id suffixes and jurisdiction support. The description compensates for the 14% schema coverage gap with practical usage guidance.

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: 'Return a company's filing history' with specific details about what each filing contains (filing_id, filing_date, category, description, document_id, jurisdiction_data) and that results are newest-first. It distinguishes from siblings like get_document_metadata and fetch_document by explaining the relationship, and from other list/search tools by focusing specifically on filings.

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 vs alternatives: it mentions using the optional 'category' parameter to filter, explains when to use get_document_metadata/fetch_document for document retrieval, and explicitly states that unsupported jurisdictions return 501 with the alternative to call list_jurisdictions for per-country caveats. It also distinguishes from sibling tools by explaining the document_id relationship.

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, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: the two distinct response shapes, the 400 error for no parameters, and the case-insensitive handling of jurisdiction codes. 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?

Extremely efficient and well-structured: first sentence establishes purpose, bullet points clearly explain the two modes, and final sentences cover error cases and sibling differentiation. Every sentence earns its place with zero wasted words.

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

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

Given the tool's complexity (two distinct modes with different return shapes), the description provides excellent context about what information is returned in each mode. However, without an output schema, the description doesn't fully document the return structure details. The annotations provide good safety coverage, making this mostly 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 fully documents both parameters. The description adds some semantic context about what each parameter triggers (full schema vs. cross-country matrix) and provides example values, but doesn't add syntax or format details beyond what the schema provides. Baseline 3 is appropriate when 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 provides 'Per-country reference data dictionary' with two specific modes: full schema for one country or cross-country matrix for one tool. It distinguishes from sibling 'about' by specifying this tool is for jurisdiction-specific reference data while 'about' is for server-level info.

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

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

Explicit guidance is provided: 'pass EXACTLY ONE of' the two parameters, with clear examples of each mode. It explicitly states when NOT to use this tool ('For server-level info... call `about` instead') and provides the consequence of incorrect usage ('Calling with no parameters returns a structured 400').

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, idempotentHint=true, etc., but the description adds crucial behavioral context: per-tier caps on country searches (anonymous=3, pro=10, etc.), confirmation dialogs for multi-jurisdiction mode, error handling for unsupported clients, cache bypass via 'fresh' parameter, and detailed output field explanations (unified fields vs. jurisdiction_data). It also notes that follow-up tools don't count against caps, enhancing operational understanding.

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 (calling modes, caps, preferences, returns, caveats) and uses bullet-like formatting for readability. It's appropriately detailed for a complex tool but could be slightly more concise by reducing some repetitive explanations (e.g., the confirmation dialog is mentioned multiple times). Every sentence adds value, but minor trimming is possible.

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 (62 parameters, no output schema), the description provides comprehensive context: it explains the two main calling modes, tier-based caps, confirmation behavior, return fields, per-country caveats, and references to other tools for further details. It compensates for the lack of output schema by describing the return structure and status field semantics, making it complete for agent usage.

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 baseline is 3. The description adds value by explaining the two primary modes (jurisdiction vs. jurisdictions) and their semantics, which aren't fully captured in the schema's individual parameter descriptions. It also hints at parameter interactions (e.g., query may be empty for FR/IE with structured filters) and directs to list_jurisdictions for per-country details, though it doesn't detail all 62 parameters individually.

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 searches company registries by name or keyword, specifying two distinct calling modes (single vs. multi-jurisdiction). It distinguishes itself from siblings like search_companies_near_point by focusing on registry search rather than geographic proximity, and from get_company_profile by being a search rather than a direct lookup.

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 each mode: use jurisdiction (singular) when the user names a specific country, and jurisdictions (plural) when uncertain. It warns to prefer the singular mode when in doubt and explicitly mentions follow-up tools (get_company_profile, list_filings, etc.) that don't count against caps, helping differentiate from 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?

The annotations already declare this as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it explains the investigative workflow (using officer_id with get_officer_appointments), describes partial name matching behavior, and clarifies what data is returned (officer_id, name, number of appointments where available). It doesn't mention rate limits or authentication needs, but adds meaningful operational context.

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

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

The description is perfectly structured with three sentences that each earn their place: first states the core functionality, second explains the output and next-step workflow, third provides strategic context about investigation patterns. No wasted words, front-loaded with essential information.

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

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

Given the tool's moderate complexity, rich annotations, and lack of output schema, the description provides excellent completeness. It covers purpose, usage patterns, behavioral context, and workflow integration. The annotations handle safety and idempotency, while the description adds investigative context and output interpretation guidance.

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 67% schema description coverage, the description adds meaningful context beyond the schema. While the schema documents the parameters technically, the description explains the investigative purpose of the 'query' parameter and the relationship between this search and subsequent lookups using officer_id. It doesn't provide additional syntax details for parameters, but adds strategic context about how parameters fit into workflows.

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 ('Find people who hold or have held officer positions'), resource ('registry for company officers'), and scope ('by name'). It explicitly distinguishes this tool from its sibling 'get_officer_appointments' by explaining the relationship between them, 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 explicit guidance on when to use this tool ('entry point for "follow the human, not the company" investigations') and when to use an alternative ('Use the officer_id in get_officer_appointments to retrieve every company that person has been appointed to'). It also mentions jurisdictional constraints through the input schema, though not directly in the description text.

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