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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds detailed response shapes, behavior for oversized documents, and instructions on not quoting from navigation tools. 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.

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

The description is long but well-structured with sections and front-loaded purpose. Some redundancy exists, but it remains efficient for the complexity.

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 params, output schema), the description covers error behavior, response types, oversized documents, and usage with sibling tools. The output schema likely documents return values, so no gap.

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%, baseline 3. The description adds meaning beyond the schema by explaining the purpose of document_id, the effect of max_bytes, and the role of override parameters.

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 that the tool reads a filing's content by document_id. It distinguishes itself from siblings like list_filings (metadata) and get_document_navigation (navigation).

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 explains when to use the tool (to get actual content) and provides critical instructions for failure scenarios. It does not explicitly state when not to use it, but the context is clear.

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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds operational details: explains field split (unified vs. raw), status enum, address flattening, per-country include options, and cache bypass via 'fresh' parameter. No contradictions 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 lengthy but well-structured, front-loading the main purpose and then covering fields, exclusions, and usage tips. Each sentence adds value, though slight condensation could improve conciseness.

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 (4 params, output schema, sibling tools), the description covers all essential aspects: what is returned, what is excluded, how to get related data, parameter usage via cross-tool references, and cache behavior. It is fully complete for an AI agent.

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 already detailed parameter descriptions (e.g., jurisdiction lists countries, company_id gives examples, include describes per-country fetches). The tool description does not significantly enhance these explanations, so 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 states 'Fetch the structured profile of a company by its registry-specific ID', providing a specific verb and resource. It explicitly distinguishes from siblings by noting what it does not bundle (officers, shareholders, etc.), ensuring 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 gives explicit when-to-use guidance: 'Does not bundle officers / shareholders / filings / charges — call those tools separately.' It also instructs to pull company_id from search_companies and to call list_jurisdictions for per-country details, providing clear context and 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?

Annotated readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint true. Description augments with: raw upstream fields in jurisdiction_data, 404 on synthesized IDs, 501 for unsupported jurisdictions, paywalled body on empty formats. 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.

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

Concise, well-structured: purpose first, then usage guidelines, then caveats. Every sentence 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?

For a 3-param tool with output schema and annotations, description covers all critical aspects: purpose, inputs, usage flow, error conditions, and behavioral notes. No 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 coverage 100%, each parameter has description. Description reinforces document_id origin and jurisdiction support via list_jurisdictions. Adds meaning beyond schema with caveats and context.

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?

Explicitly states it retrieves metadata for a filing document by document_id from list_filings. Distinguishes from sibling fetch_document by advising to call this tool first when document may be large or format unknown.

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?

Provides clear when-to-use guidance: before fetch_document, when size or format uncertainty. Also gives explicit warnings: do not construct document_id, synthesized IDs will 404, empty formats indicate paywalled content, unsupported jurisdictions return 501.

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?

Adds beyond annotations: mentions precondition (document must be cached), notes truncation/OCR errors, and warns not to cite directly. 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?

Three paragraphs with clear structure: purpose, usage, caveats. Front-loaded with purpose. Each sentence adds value; no 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 tool complexity, high schema coverage, and annotations, the description fully addresses purpose, preconditions, usage, and limitations. Output schema exists, so return values need not be detailed.

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 for all 5 parameters. Description adds limited new parameter-specific info (e.g., caching requirement) but baseline is 3 due to 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?

Description clearly states it returns a navigation index for cached documents, listing specific elements (outline, previews, landmarks). It distinguishes from sibling fetch_document by advising to call this first for large PDFs.

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 says to call this first for large PDFs, then use fetch_document with page range for authoritative content. Also warns that navigation aids are not reliable for citations, guiding proper usage.

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 confirm read-only, non-destructive, idempotent behavior. The description adds valuable behavioral details: default include_resigned flag, handling of role labels in native language, birth-date precision variations, corporate officer ID mapping, GDPR masking, and 501 for unsupported jurisdictions. 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.

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

The description is moderately sized but efficiently front-loaded with core purpose and key behavioral details. Each sentence adds value, though could be slightly more structured (e.g., bullet points for limitations).

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 (multiple jurisdictions, officer types, data nuances), the description covers all critical aspects: scope, defaults, language, privacy, id stability, error handling. With full schema coverage, annotations, and an output schema, the description is sufficiently 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 coverage is 100% with parameter descriptions. The description adds extra meaning: group_by_person is CZ-only, jurisdiction string refers to full capability via list_jurisdictions, and fresh bypasses cache. This enhances understanding beyond schema alone.

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 a company's officers including current and historical, with specific roles enumerated. It differentiates the tool's scope from siblings like get_shareholders or search_officers, making 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 usage context like default behavior (include_resigned=true), language handling for role labels, birth-date precision, and id stability. It mentions unsupported jurisdictions returning 501 and directs to list_jurisdictions for details. Lacks explicit when-not-to-use versus 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, destructiveHint, idempotentHint, openWorldHint. The description adds valuable behavioral context: the data source (statutory equity roster), legal-form-conditional disclosure, possible empty list/document pointer/explanation responses, and preservation of raw upstream fields. This goes well beyond the 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 front-loaded with the core purpose and well-structured across three paragraphs. Each sentence adds value, though slightly verbose. Still, it maintains clarity without unnecessary repetition.

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 of distinguishing shareholders from beneficial owners and conditional disclosures, the description covers all important scenarios: empty list, document pointer, statutory explanation, unsupported jurisdictions. It references sibling tools and explains response flags. No gaps remain.

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?

The description does not add new information about parameters beyond what the input schema already provides. However, schema coverage is 100% and the schema descriptions are already detailed and extensive, so the baseline score of 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 explicitly states 'Return the shareholders / members / quota-holders — the legal-statutory equity roster published by the registry, no ownership-threshold filter.' This provides a specific verb and resource, and effectively distinguishes from siblings like get_officers or fetch_document.

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 says 'Use this for any shareholder / member / quota-holder question.' It clearly differentiates from beneficial owners (PSC/UBO) and explains when results may be empty or point to a document. It also mentions unsupported jurisdictions return 501, providing complete guidance.

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 discloses behavioral traits beyond annotations, such as the preservation of raw upstream fields under jurisdiction_data, the meaning of has_document=false (paywalled/unavailable), and the cache-bypass behavior of the fresh parameter. Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, and the description does not contradict them.

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. It uses short, informative paragraphs covering response fields, filtering, usage notes, pagination, and error handling. Every sentence adds value without redundancy. It is concise yet comprehensive.

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, multiple jurisdictions, pagination, output schema), the description covers all essential aspects: core function, response structure, optional filtering, how to retrieve document bytes, pagination details, error codes, and cache bypass. It references sibling tools for further details, making it 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?

With 100% schema coverage, the baseline is 3, but the description adds significant value: it explains the category parameter's normalized vs native values, the pagination parameters (cursor for GB, offset for IE), and the fresh parameter's meaning. It also clarifies the jurisdiction parameter's format and how to get per-country info. This enriches 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 clearly states the tool returns a company's filing history, newest first, specifying the verb 'return' and resource 'filing history'. It distinguishes from sibling tools like fetch_document (actual bytes) and search_companies (search). The description also lists common categories and mentions unsupported jurisdictions, providing a clear purpose.

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 (for metadata only) and when not to (call fetch_document for actual filing bytes). It provides guidance on filtering by category, pagination with limit/cursor/offset, and error handling for unsupported jurisdictions. It also directs users to list_jurisdictions for per-country details, offering clear usage guidelines.

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 read-only, non-destructive, idempotent behavior. The description adds value by specifying the detailed return content for each parameter, 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 extremely concise, using bullet-like formatting with backticks. Every sentence is necessary, and the key instruction 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?

Given the presence of an output schema, the description need not detail return values. It completely explains the two usage modes and their outputs.

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. The description adds significant context beyond the schema, listing specifics like registry name, data license, and tool support matrix.

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 defines the tool as a per-country reference with two mutually exclusive parameters. It specifies exact outputs for each parameter, distinguishing it from other tools that fetch company 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 explicitly states to pass exactly one parameter, making usage clear. It does not explicitly mention alternatives, but the context shows it is for metadata lookup, distinct from 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?

Beyond annotations (readOnly, idempotent), the description adds behavioral details: fresh parameter bypasses cache, multi-country elicitation, tier limits, and return fields. 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?

Well-structured with bullet points for options, front-loaded purpose, and every sentence adds value. No fluff; appropriately sized for the complexity.

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 all key aspects: required/optional params, mutual exclusivity, caching, pagination, user confirmation, tier limits, filter delegation, and return fields. Output schema exists, so return value details are handled there.

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?

Even with 100% schema coverage, the description adds significant meaning: clarifies mutual exclusivity of jurisdiction/jurisdictions, provides examples for query (e.g., AU key:value pairs), and explains filters as per-country schemas referencing list_jurisdictions.

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: 'Search a national company registry by name or keyword.' It uses a specific verb (search) and resource (company registry), and distinguishes from sibling tools like search_officers and list_jurisdictions.

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?

Provides explicit guidance on when to use jurisdiction vs jurisdictions, explains user confirmation for multi-country, mentions per-tier caps, and directs to list_jurisdictions for country-specific filters. This covers when to use and 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 mark the tool as read-only, non-destructive, and idempotent. The description adds value by specifying the return structure ('candidates with officer_id, name, and (where exposed) appointment count') and directing users to list_jurisdictions for per-country details. 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.

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

The description is two sentences, front-loaded with the core action, and no redundant words. Every sentence provides value: first sentence defines purpose, second clarifies output and usage context.

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 (3 params, output schema, annotations), the description adequately covers purpose, output structure, and provides a usage hint. It references additional resources (list_jurisdictions) for completeness. Could be slightly more explicit about error or edge cases, but overall 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?

All three parameters are fully documented in the schema (100% coverage). The description adds useful context for the jurisdiction parameter, listing supported countries and referencing list_jurisdictions for more details, which goes beyond the schema's description.

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?

Description clearly states 'Find people holding or who held officer positions... by name' and specifies officer types (director, secretary, member, partner). It also positions the tool as an 'Entry point for person-centric investigations,' distinguishing it from sibling tools like get_officers which are company-centric.

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 person-centric investigations but does not explicitly state when not to use this tool or provide direct alternatives. For example, it doesn't mention that get_officers should be used for officers of a known company.

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