capabilities

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context: it returns a derived overdue flag, mentions pricing (USD 0.003/call), and clarifies that financial figures are not available from the public register API. 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 concise (4 sentences) and well-structured: purpose, use case, exclusion, related tools, pricing. Every sentence adds value. It is front-loaded with the primary action and returns. No unnecessary 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 an output schema exists (not shown), the description does not need to detail return values but still names the key fields. It covers pricing, use case, and limitations. With only one parameter, full schema coverage, and annotations covering safety, the description is 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%, so baseline is 3. The tool description does not add any additional parameter semantics beyond what the schema already provides. The schema's description of 'company_number' is thorough, but the tool description itself does not elaborate on 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 the tool returns accounts filing status, reference date, last accounts filed, next due date, and overdue flag. It names the specific resource (UK company accounts) and verb ('Return'). It mentions related tools but does not explicitly differentiate when to use this tool over them, preventing a perfect score.

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 'Use when' and 'Not for' sections provide clear guidance. The use case is stated as 'When are this UK company's accounts due?' and the exclusion of financial figures is noted. Related tools are listed, offering alternatives. This is exemplary usage 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds context about the price per call and account key pricing, which is valuable for cost-aware agents. 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 a main sentence, usage guidelines, related tools, and pricing. It is front-loaded with the core purpose. However, the parameter descriptions in the schema are lengthy and could potentially be slightly more concise without losing meaning.

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 has 5 parameters (1 required), 100% schema coverage, an output schema, and comprehensive annotations, the description is complete. It explains what the tool does, when to use it, what not to use it for, pricing, and the limitations of server-side filtering. The presence of an output schema means return values don't need explanation in the description.

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%, but the description adds significant value beyond the schema. It explains why the default limit is low (3) due to charge size, clarifies that offset is a zero-based register index (not filtered result index), details how the status filter works client-side (Eckari reads up to 3 register pages of 100 charges), and provides edge-case handling for company_number (whitespace stripping, zero-padding, and rejection conditions). This far exceeds what the schema alone 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 charges and mortgages from Companies House, specifying the types (mortgages, debentures, other security) and key fields (dates, classification, particulars, persons entitled). It distinctly separates this from sibling tools like company_uk_status and company_uk_profile.

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 'Use when' guidance (checking outstanding security and who holds it) and 'Not for' guidance (insolvency proceedings, referencing resource flags on company.uk.profile). It also lists related tools (company_uk_profile, company_uk_filings, company_uk_status) to help the agent navigate 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details filtering logic, pagination behavior (reads up to three pages, limit handling), and error handling (INVALID_INPUT before payment). Rich behavioral 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 somewhat long but front-loaded with core purpose and usage. Every sentence adds value, though some technical details could be slightly more concise. Still well-structured for clarity.

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 complexity (5 parameters, output schema, annotations), the description is complete: covers purpose, usage, behavioral details, parameter semantics, pricing, and error handling. 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 is 100%, but the description adds significant meaning: e.g., the role parameter explains the substring test and defaults; limit and offset explain pagination mechanics; company_number details validation and zero-padding.

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 it lists UK company directors from the Companies House officers register, and specifies the data returned (appointment dates, nationality, etc.). It also differentiates from the sibling tool company_uk_owners for beneficial owners.

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 'Use when' and 'Not for' guidance, including the alternative tool company_uk_owners. This directly addresses when to use this tool versus 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by specifying pricing (USD 0.005/call) and the page.has_more logic, though it doesn't detail any rate limits or additional failure modes beyond INVALID_INPUT for whitespace-only company numbers.

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 concise and front-loaded with the main purpose, followed by usage guidance and pricing. The 'Not for' and pricing sections could be more succinct, but overall every sentence earns its place without redundancy.

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

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

Given the presence of an output schema (sibling tools indicate this is a well-structured tool), the description doesn't need to explain return values. It covers what the tool does, when to use it, and key output fields. The only minor gap is not mentioning pagination behavior explicitly (aside from the offset description), but the output schema likely handles that.

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 provides a readable overview of what the tool returns, but the parameter details (e.g., limit, offset, category patterns) are already fully documented in the schema. The description does not add new meaning beyond the schema's 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 filing history from Companies House, specifying the types of filings (accounts, confirmation statements, officer appointments, etc.), order (most recent first), filters (category), and key output fields (date, form type, register description, annotations, document URL). This is specific enough to distinguish it from siblings like company_uk_directors.

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 'Use when: What has this UK company filed recently?' and 'Not for: You need the current directors themselves...use company.uk.directors.' This provides clear guidance on when to use this tool versus an alternative, fulfilling the highest standard for 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, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond these annotations by explaining that an empty items list does not mean 'no owner' and that ownership_status and PSC statements/exemptions explain why the register discloses none. This helps the agent interpret results correctly.

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 concise and front-loaded with the most critical caveat (empty list vs no owner), followed by usage guidance and pricing. Each section is labeled and earns its place, with no redundant fluff.

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 rich schema and output schema, the description covers the essential caveat, usage context, related tools, and pricing. While it doesn't detail pagination (handled in schema), the description is sufficiently complete for an agent to select and invoke the tool correctly.

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 parameters are fully documented in the schema. The description does not add any additional parameter semantics (e.g., behavior of limit/offset). It provides no value beyond the schema, hence the baseline score of 3.

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 via 'Use when: Who owns this UK company?' and distinguishes it from sibling tools with 'Not for: You need directors/officers rather than owners — use company.uk.directors.' This effectively communicates that the tool returns beneficial owner data, matching the title.

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 usage guidance is provided: 'Use when: Who owns this UK company?' and 'Not for: You need directors/officers rather than owners — use company.uk.directors.' It also lists related tools, giving the agent clear decision criteria.

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, and idempotentHint=true, so the agent knows this is a safe read. The description adds helpful context: the derived fields (is_active, is_striking_off) and the price tiers ($0.004 and $0.003/account key). It does not discuss rate limits or pagination, but for a single-record lookup with no pagination this is acceptable.

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 three sentences—front-loaded with the core purpose, followed by usage conditions and pricing. It is concise but could drop the price detail to be slightly more streamlined, or integrate pricing elsewhere. Still, it efficiently packs essential information without redundancy.

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

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

Given that an output schema exists (so return format is documented), only 1 parameter, and rich annotations, the description is complete. It covers the tool's scope, when to use, when not to, input formatting nuances, and cost context. There is no missing information that would hinder correct selection or invocation.

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 baseline is 3. The description adds value beyond the schema by explaining that short numeric values are zero-padded, and whitespace-only or over-long values cause rejection before any upstream call. This gives the agent practical input-formatting knowledge beyond the regex pattern.

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 starts with a specific verb ('Return') and identifies the exact resource ('core registered profile of a UK company from the Companies House register'). It lists key fields returned (name, status, is_active, etc.), making it easy to distinguish this from sibling tools like company_uk_status (which only provides active/inactive status).

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 ('You have a UK company number and need the standard registered record') and when not to ('You only need to know if the company is active — use company.uk.status'), even naming the cheaper alternative. This is exemplary 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?

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive, so the description doesn't need to repeat those. However, the description adds context about pricing (USD 0.003/call, reduced with account key) and implicit behavior around whitespace handling and zero-padding of company numbers, which goes beyond the structured fields. A 4 is appropriate because while annotations already cover safety, the description adds valuable 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 two sentences plus a brief usage/pricing note, which is concise and front-loaded. The first sentence immediately states the purpose and output format. However, the pricing information could be trimmed or moved to annotations, and the parenthetical note about whitespace/zero-padding arguably belongs in the schema (which already covers it). Slightly redundant but still 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 has only one parameter, a complete schema, clear annotations, and an output schema (which handles return value documentation), the description covers all necessary aspects: purpose, usage scenario, exclusions, related tools, and pricing. It does not need to describe return values since an output schema exists. A 4 reflects that it is complete and well-integrated with the structured metadata, though the pricing snippet is a minor bonus not strictly needed.

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% since there is only one parameter (company_number) and its schema description is detailed (explains CRN, length, whitespace handling, zero-padding, and error conditions). The tool description does not add further meaning to this parameter beyond the schema, so baseline 3 is correct. No additional parameter info is needed given the 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 uses a specific verb ('Return') and a clear resource ('current registered office address of a UK company from the Companies House register'). It distinguishes itself from siblings by explicitly stating what the tool outputs (structured fields plus a single-line rendering) and by naming an alternative (company.uk.profile) that already includes this address, making its narrow scope obvious.

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 'Use when' and 'Not for' guidance with a concrete example ('What is the registered office address of company 00445790?'). It names an alternative tool (company.uk.profile) that should be used when the whole profile is needed, and lists related tools for further context. This gives the agent clear decision-making criteria.

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, openWorldHint, idempotentHint, and destructiveHint as false, providing a strong behavioral baseline. The description adds valuable context about pricing per call and account-level discounting, which is not in annotations. However, it doesn't describe pagination behavior beyond what's hinted in the schema description for offset.

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?

Four sentences, front-loaded with the core purpose, then usage guidance and pricing. Every sentence adds value with no redundancy. Extremely 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 moderate complexity (3 params, simple return), existing annotation coverage, and complete schema documentation, the description is fully adequate. It covers purpose, usage rules, behavioral traits (pricing), and relationships to siblings. The output schema exists but is not shown here, so no need to describe 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 three parameters fully described (q, limit, offset). The description adds minimal semantic value beyond listing some return fields. Baseline 3 is appropriate since the schema already 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 it searches the UK Companies House register by name or keyword, listing specific return fields. It distinguishes itself from siblings by explicitly mentioning what not to use it for when a company number is known, and names alternative tools (company_uk_profile, company_uk_status).

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 ('Look up a UK company by name'), when not to use ('You already have the company number'), and provides clear alternatives. This level of guidance is exemplary.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: details about derived fields (is_active, is_striking_off), parameter constraints, and pricing. 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?

Two concise sentences plus structured 'Use when/Not for/Price' lines. No redundant information; every sentence earns its place. Front-loaded with key purpose and results.

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 an output schema exists (not shown but stated), the description does not need to describe return format. It already covers status types, derived fields, parameter constraints, pricing, and usage guidance. Fully complete for a single-parameter status lookup tool.

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%; the input schema already fully documents the company_number parameter (pattern, whitespace handling, zero-padding). The description adds no additional parameter meaning beyond the implicit context of a UK company. 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 explicitly states the tool returns the 'current legal status of a UK company' and lists specific statuses (active, dissolved, etc.) and derived fields (is_active, is_striking_off). It distinguishes from sibling company_uk_profile by specifying what the tool does not do.

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 'Use when' and 'Not for' guidance, including a direct sibling alternative (company.uk.profile). Also mentions price, which helps the agent decide based on cost.

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 readOnly, openWorld, idempotent, and not destructive. The description adds pricing info, states that NOT_FOUND is not billable, and implies result includes document links. 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?

Five sentences: purpose, use when, not for, related tools, pricing. Front-loaded with essential info, no fluff, each 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?

Given 5 parameters, output schema exists, and annotations cover safety, the description covers usage, limitations, pricing, and non-billable case. It is complete for an agent to decide on tool selection and invocation.

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 each parameter. The description adds no new semantic details beyond summarizing optional filters and paging. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns recent EDGAR filing history for a US company by ticker or CIK, with optional filtering and paging. The verb 'Return' and resource 'EDGAR filing history' are specific. It also lists related tools for 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?

Explicit 'Use when' example (list every 8-K this year) and 'Not for' scenario (need filer identity, which is not provided). Also mentions related tools and pricing, giving clear context for when to use this tool vs 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 declare readOnly, idempotent, and non-destructive hints, so the burden on the description is lighter. The description adds useful behavioral details: it returns filing and report dates, a direct sec.gov link, and notes that a ticker without SEC index entry returns NOT_FOUND as a non-billable result. It does not elaborate on pagination or result limits, but the output schema presumably covers the structure. This is strong 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 three sentences, front-loaded with the core function, then a usage guideline section, then pricing. Each sentence earns its place. It could drop the pricing line or move it to annotations, but it doesn't hurt clarity. Minor structural waste from the pricing sentence, which might be better as a note, 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 moderate complexity, 100% schema coverage, and presence of an output schema, the description covers all essential aspects: what it does, how to use parameters, when to use it, behavioral quirks (CIK normalization, NOT_FOUND non-billable), and limitations (no filer identity). The output schema presumably documents the return structure, so no need to repeat it. Complete for an agent to confidently select and invoke.

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%, so baseline is 3. The description adds meaningful context beyond the schema: it explains how CIK prefixes and leading zeros are handled, that tickers are matched case-insensitively, that company names are not accepted (pointing to company_us_resolve), and the default form list. The form parameter gets clarity on matching and ordering. The extra explanations elevate this to a 4.

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 it retrieves the most recent EDGAR filings (10-K, 10-Q, 8-K) for a US company given a ticker or CIK, providing dates and direct sec.gov links. This is a specific verb+resource combination that distinguishes it from siblings like company_us_filings (which may retrieve historical filings) and company_us_resolve (which resolves company names).

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 says 'Use when: What is Apple's latest 8-K, and where is the document?' and provides a clear 'Not for:' case explaining that it doesn't return filer identity and unsuitable for ownership forms. This gives direct when-to-use and when-not-to-use guidance, and implicitly steers users toward siblings like company_us_profile for other needs.

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 (readOnlyHint, idempotentHint) are complemented by the description's details: missing ticker returns NOT_FOUND (non-billable), company names are not accepted, and the tool provides price per call. 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 compact yet rich, front-loading purpose and key fields, then adding usage guidance and pricing. Every sentence serves a purpose with 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?

With only one parameter, an output schema present, and annotations covering safety and idempotence, the description fully covers what the agent needs: what it returns, when to use, when not, and cost. 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?

Input schema covers 100% of the single parameter with a detailed regex and description. The description reinforces the parameter behavior (CIK vs ticker) and adds that company names should be resolved via company.us.resolve, which is useful 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 returns an SEC filer's registered profile by ticker or CIK, listing specific fields (legal name, entity type, SIC, etc.). It distinguishes from siblings like company.us.filings.latest and company.us.resolve by mentioning what the tool does not do (reporting status, name resolution).

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?

Includes explicit 'Use when' (exchanges/tickers) and 'Not for' (reporting status) sections, with a direct reference to the alternative tool company.us.filings.latest. Also mentions pricing, helping the agent evaluate cost sensitivity.

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, idempotentHint, and openWorldHint, so the description's burden is low. The description adds context about matching behavior (case-insensitive, trimmed, no fuzzy matching) and pricing. However, it does not elaborate on ranking criteria or pagination beyond what the schema already provides for the limit parameter.

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 very concise: two initial sentences state the action, followed by structured use-case guidance and pricing. Every sentence serves a distinct purpose, and the 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?

Combined with the input schema (100% covered), annotations, and an output schema, the description covers all essential aspects: input type, use cases, when not to use, related tools, and pricing. The tool is simple and the description is complete enough for an agent to correctly select and invoke it.

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 does not add new semantic information beyond echoing the schema (e.g., matching details, limit behavior). Therefore the description provides no additional value for parameter understanding.

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

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

The description explicitly states the tool converts a company-name fragment or stock ticker into SEC EDGAR identifiers (CIK and ticker). It distinguishes itself from sibling tools by specifying what it is not for and naming alternatives that accept identifiers directly.

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 'Use when' and 'Not for' sections with examples and names specific alternative tools (company.us.profile, company.us.filings, company.us.filings.latest). Also lists related tools and pricing, giving clear guidance on when to call this tool versus others.

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, openWorldHint, idempotentHint, and no destruction. The description adds that the tool reads 'live from the authoritative registry RDAP server' and includes pricing details (USD 0.002/call). This provides useful behavioral context beyond annotations, though it could mention rate limits or authentication needs if any.

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

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

The description is a single paragraph with clear front-loading: first sentence states the core functionality and outputs, second sentence outlines usage boundaries. Every sentence adds value with no redundancy or fluff.

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 low tool complexity (1 parameter, output schema present), the description fully covers what the tool returns, when to use it versus alternatives, and pricing. No gaps are evident for effective agent invocation.

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% for the single parameter 'domain'. The schema already thoroughly describes the parameter format (bare domain, punycode conversion, rejection of URLs/paths). The tool description does not add new parameter-level semantics beyond stating it accepts a domain name. Baseline score of 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: check domain expiry date and days remaining using RDAP. It lists specific outputs (registry status codes, registrar name, last-update timestamp). It also distinguishes itself from the sibling tool 'domain_registration' by noting it is a cheaper subset focused on renewal monitoring, thereby avoiding ambiguity.

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 ('When does this domain expire?') and when not to ('Not for: You also need nameservers, DNSSEC... - use domain.registration'). It also mentions a related tool (domain_registration), providing clear guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds valuable context: the data is retrieved live via the IANA bootstrap (not scraped WHOIS text), and the pricing is disclosed ($0.004/call). This goes beyond the annotations, though it does not detail failure modes or latency which would be needed for 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 a clear opening sentence, followed by 'Use when' and 'Not for' sections, and a pricing note. It is front-loaded with the essential purpose. The pricing information, while helpful, adds slight length but does not detract from readability. Nearly every sentence earns its place, earning a high score.

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 low complexity (single parameter, clear annotations, output schema present), the description is fully complete. It covers purpose, usage guidelines, data source, pricing, and alternatives. The agent has all necessary context to decide whether to invoke this tool, and the output schema handles return values without needing description.

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 only one parameter and 100% schema description coverage, the input schema already provides rich semantics (pattern, length limits, punycode conversion, URL/port rejection). The tool description does not add further meaning about the parameter beyond restating its purpose. Baseline of 3 is appropriate given the schema carries the load.

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 performs WHOIS lookup via RDAP, specifying it returns registrar, creation date, expiry, transfer lock. It distinguishes itself from the sibling domain_expiry by noting that tool is cheaper and limited to expiry dates. The verb 'lookup' and resource 'domain' are specific, and the data source (registry RDAP) is explicit.

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 'Use when' and 'Not for' conditions, directly referencing the sibling tool domain_expiry as a cheaper alternative for expiry-only queries. It also lists concrete use cases (registrar, creation date, expiry, transfer lock), giving clear guidance on when to invoke this tool versus 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the input validation behavior (checksum checked before execution, never charged for bad checksums) and pricing. This provides behavioral context beyond the annotations, though it could be slightly more explicit about the read-only nature.

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 sections for purpose, usage guidance, related tools, and pricing. It front-loads the core functionality. However, the list of return fields is somewhat redundant given the output schema, making it slightly longer than necessary. Still, it remains concise overall.

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 single parameter, rich annotations, and presence of an output schema, the description covers all necessary context: purpose, when to use, alternatives, pricing, validation behavior, and related tools. It is fully complete for the tool's 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?

The input schema provides 100% coverage for the single parameter 'lei', with a detailed description including pattern, length, and checksum validation. The tool description adds 'Legal Entity Identifier' but does not significantly augment the schema's semantics. Given high schema coverage, a 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 clearly states 'Return the registry-authoritative GLEIF record for a Legal Entity Identifier' and lists specific fields (names, addresses, jurisdiction, etc.), using a specific verb and resource. It distinguishes from the sibling entity_lei_search, which is used when the input is a company name rather than an LEI.

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 includes explicit 'Use when' and 'Not for' sections, stating to use when looking up everything the LEI register holds, and not for company name searches (directing to entity_lei_search). It also lists related tools, providing clear guidance on when to use this tool versus 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 read-only, open-world, idempotent. Description adds valuable behavioral context: GLEIF applies its own matching, Eckari does not re-rank, pagination limitations (limit capped at 25 due to hydration constraints, offset capped at 9900 due to GLEIF restrictions). This goes beyond what annotations provide.

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

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

Two sentences plus structured usage/not-for/related section. No redundant information. Front-loaded with core purpose, then use guidance. Pricing included sans clutter.

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 complexity (4 parameters, output schema exists), the description covers purpose, usage, behavior, parameter semantics, and return fields (LEI, legal name, etc.). Output schema likely details return structure further, so description is sufficient without being overlong.

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%, so baseline 3. Description adds significant meaning: explains how GLEIF matching works for parameter q, why limit is capped at 25, offset pagination mechanics (page number vs offset), ISO code format for country. All param descriptions provide practical context beyond 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 explicitly states it finds Legal Entity Identifiers by company name in the GLEIF register, with optional country filter, and lists returned fields. It distinguishes from sibling tools by specifying when to use entity_lei_profile instead and relation to company register tools.

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?

Directly states 'Use when: What is the LEI for this company?' and 'Not for: You already have the LEI — use entity.lei.profile.' Also names related tools, providing clear decision guidance. Includes pricing info helpful for cost-aware agents.

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, idempotentHint, destructiveHint false. The description adds that the rate covers latest or any date in the last 90 days, that ECB publishes EUR/XXX only with derived rates named in rate_derivation, and mentions pricing. It also notes date fallback to prior fix on non-publishing days. This adds behavioral context 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?

Description is a few sentences but each adds value: purpose, limitation (EUR/XXX only), usage guidance, pricing. It front-loads the main purpose. Could be slightly tighter, but no fluff.

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 three parameters and existence of output schema, the description covers purpose, usage, behavioral details, limitations, and pricing. It is complete for an agent to select and invoke correctly without further clarification.

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 base, quote, and date. The description adds semantic value: explains that EUR/XXX is the native fix (inverse/cross computed) and that date returns latest prior fix if no ECB fix on that day. This goes beyond the schema's 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 it returns 'European Central Bank euro foreign exchange reference rate' for a pair, specifying it's the official daily fix for accounting, invoicing, and reporting. It distinguishes itself from live/tradable rates and mentions that inverse/cross rates are computed, giving a precise scope.

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 'Use when' and 'Not for' sections: use for official daily rates verifiable against ECB, not for executable/live/intraday rates. This provides clear context for when to invoke this tool versus alternatives like live rate APIs.

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, idempotentHint, and destructiveHint. The description adds critical behavioral context: 'Coordinates are interpolated along street address ranges, not rooftop or parcel positions.' It also includes pricing information. 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 a clear lead sentence, output details, precision caveat, usage guidance, related tool, and pricing. It is slightly long but every sentence adds value. Front-loaded with core 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 presence of an output schema (not shown here), the description does not need to detail return values. It covers purpose, precision limitations, usage guidance, pricing, and related tool. The paging behavior is documented in the schema parameter descriptions. The description is complete for an agent to make an informed decision.

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 detailed parameter descriptions for limit, offset, and address. The description does not add additional semantics beyond what the schema provides, though it confirms the address format. 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 clearly states the tool converts a one-line US street address into coordinates using the US Census Bureau Geocoder. It specifies the output includes latitude/longitude to 6 decimal places, TIGER/Line segment, and parsed address components. The related tool 'location_us_geographies' is mentioned, distinguishing it from a 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 provides 'Use when' and 'Not for' guidance, stating rooftop/parcel precision is not available. References the related tool 'location_us_geographies' as an alternative. This gives clear direction on when to use this tool versus 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds return value context (list of geographies with FIPS/GEOID) and pricing, consistent with annotations. 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?

At ~85 words, the description is concise and well-structured: purpose first, then returns, then use cases. Could be slightly tighter, but no wasted sentences.

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 simple coordinate-to-geography lookup with 2 required params, existing annotations, and an output schema, the description covers the return types, use case, sibling distinction, and pricing—complete and actionable.

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 clear descriptions for both lat and lon. The description repeats 'latitude/longitude' but adds no semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns US Census geographies for a lat/lng, lists specific geography types (state, county, census tract, etc.) with FIPS/GEOID, and distinguishes from sibling location_us_geocode by specifying coordinates vs. addresses.

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 use when ('Which county and census tract is this coordinate in?'), not for ('You have an address'), and names the alternative (location.us.geocode first). Also includes pricing, aiding agent decision-making.

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 thoroughly discloses behavioral traits beyond annotations: it is deterministic, uses a versioned signature set, explains how country hints are used only as tie-breakers without inventing candidates, and mentions pricing. The description aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds rich operational detail.

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 compact, with clear sentences covering purpose, method, output, usage guidelines, and pricing. Every sentence adds necessary information and there is no fluff. Structure front-loads the action, then method, then guidance.

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 (carrier detection, ranking, S10 parsing, pricing) and that an output schema exists, the description is impressively complete. It covers what the tool does, how it works, when/not to use it, costs, and parameter semantics. No gaps are evident for an agent to select and invoke it correctly.

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 baseline is 3. The description adds value by explaining how 'origin_country' and 'destination_country' are purely tie-breakers and never invent candidates, and how 'tracking_number' is normalized (spaces/hyphens removed, letters upper-cased). This is helpful context beyond the schema's regex and length constraints.

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: identify which carrier issued a tracking number. It uses specific verbs like 'detect' and 'identify', describes the deterministic method (prefixes, lengths, check digits, UPU S10), and lists what the tool returns. It is well-distinguished from siblings which are in different domains (company, domain, fx, location, weather).

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 provides a use case ('Which carrier is this tracking number from?') and a clear 'not for' case (tracking events, status, delivery estimates). It also mentions no upstream call or carrier account required, which sets expectations for when not to look elsewhere.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by noting that the result is read at request time ('Read at request time, so an empty list means nothing is active') and describing the limit mechanism with page.total for completeness. However, it could mention that NWS data may have latency or that the tool depends on upstream availability, which is minor.

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

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

The description is a single well-structured paragraph that front-loads the core purpose and input types, then provides usage guidance, alternatives, and pricing. Every sentence adds distinct value, and the text is streamlined with 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 the tool's complexity (6 parameters, no required ones, an output schema exists, and full annotation support), the description is complete. It covers purpose, input options, alternative tools, behavioral guarantees, and even pricing cost context. The output schema likely handles return value descriptions, so the description need not cover that.

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 well. The description adds significant meaning beyond the schema: it explains the purpose of limit ('keeps the answer compact...page.total always reports how many are active'), detail's difference ('compact returns the fields an agent decides on; full adds NWS narrative members'), and offset behavior ('the whole active set is read in one upstream request...a window over it is consistent'). This enriches parameter understanding.

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 uses specific verbs ('Get active...weather alerts') and identifies the resource ('National Weather Service watches, warnings and advisories') and location inputs ('US coordinate or a two-letter state or marine area code'). It clearly distinguishes from siblings like weather_us_forecast and weather_us_observation listed in the sibling-tools.

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 when-to-use guidance ('Decide whether an active US weather warning affects a location before dispatching or travelling'), explicit when-not-to-use ('Not for: You need the forecast rather than alerts'), and names specific alternative tools ('use weather.us.forecast', 'Related: weather_us_forecast; weather_us_observation'). It also mentions pricing to inform cost-aware decisions.

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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by noting the NWS issue time field (allowing agent to judge data freshness) and pricing (USD 0.003/call). 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 a single, dense paragraph that front-loads the core purpose before listing features, usage guidance, and pricing. It is efficient with no wasted words, though a slightly more structured format (e.g., bullet points) could improve scanning. Still, 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 6 parameters (all well-described in schema), an existing output schema, rich annotations, and a full sibling list, the description covers all essential aspects: purpose, output fields, usage boundaries, pricing, and temporal detail (NWS issue time). There are no missing pieces for an agent to correctly invoke the tool.

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 parameter descriptions. The description supplements by clarifying the default behavior ('six 12-hour day/night periods by default, or hourly') and explaining the relationship between hours and period_limit parameters. This helps an agent choose the correct combination without reading the 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 'Official National Weather Service forecast for any US coordinate' and enumerates the returned data (six 12-hour periods or hourly, with temperature, precipitation, wind, etc.). It distinguishes from sibling tools weather_us_observation and weather_us_alerts by specifying scope and 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?

Explicitly provides use-case guidance: 'Use when: What is the weather forecast for these US coordinates? Not for: You need the latest observed conditions and their age - use weather.us.observation.' It also lists related tools ('Related: weather.us.observation; weather.us.alerts'), leaving no ambiguity about when to invoke this tool versus 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the polling frequency ('every 20-60 minutes'), that it's 'the most recent measurement, not a real-time reading', and the is_stale flag – all behavioral insights 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?

Three well-structured sentences: first explains what the tool returns, second provides behavioral context, third gives usage guidance and pricing – no wasted words, front-loaded with key 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 has 2 well-documented params, a complete output schema, and full annotation coverage, the description elegantly fills gaps by explaining staleness, observation frequency, and use-case boundaries – fully sufficient for an agent to select and invoke correctly.

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 lat and lon (including rounding to 4 decimal places and WGS84 coordinate system). The description adds context by linking parameters to the nearest station lookup, but does not repeat schema information; a minor improvement would be a short mention of rounding impact.

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 uses a specific verb 'Get' with a clear resource 'latest surface observation' from a source 'nearest National Weather Service station' and lists key output fields (station identity, observed_at, age, is_stale). It distinguishes itself from siblings by mentioning US coordinates and the time-bound nature of observations.

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 ('What was the most recently observed temperature at these US coordinates?') and when not to ('Not for: You need a prediction rather than a measurement'), with direct sibling tool names (weather_us_forecast and weather_us_alerts) and pricing context, providing comprehensive guidance.

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