Ready APIs

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by listing the enrichment categories returned and noting it's a one-call operation, but does not discuss limits, input normalization, or error behavior. With annotations present, this is adequate baseline credit.

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?

A single sentence that front-loads the action and includes the key enrichment categories. No filler or redundancy; every word 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 a simple single-parameter tool with complete schema coverage, the description lists the main enrichment content (demographics, risk, climate, nearest airport, hazards) and mentions it's a one-call operation. It lacks output format details, but no output schema exists, so the listed categories are sufficient for the agent to understand the response scope.

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% (address described as 'Free-form US address: street, city, state, ZIP.'). The description echoes 'US address' and adds the enrichment context, but does not introduce new parameter meaning beyond the schema. Baseline 3 applies.

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 action ('Validate a US address') and the resource ('US address') with a specific outcome ('return the full ZIP enrichment'), listing concrete enrichment categories. It distinguishes from sibling tools like address_validate by emphasizing the enrichment result in one call.

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 context that this tool is for validation plus enrichment, making it clear when it would be preferred over a simple validation tool. It does not explicitly name alternatives or exclusions, but the use case is well-implied by the listed enrichment categories.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive). The description adds behavioral context by explaining that the tool standardizes components and cross-checks the ZIP against a geo dataset for state/city consistency, which goes beyond mere annotation repetition.

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 sentence that front-loads the core purpose and then adds specific details. Every word earns its place, with no redundancy or filler.

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

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

The tool is simple with one parameter and no output schema. Annotations provide safety context, and the description explains the processing behavior. It doesn't describe the return format, but for a validation tool this is reasonably inferable. The description is complete enough for an agent to understand core functionality.

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 'address' parameter, which already describes it as a free-form US address. The description reinforces this but adds limited additional semantic meaning beyond the schema, mainly clarifying that the tool will parse and standardize the given components.

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 a specific action ('parse and validate') on a specific resource ('free-form US address'), and goes into detail about standardization and ZIP cross-checking. This distinguishes it from sibling tools like address_enrich and address_validate_batch by focusing on validation with geo-dataset consistency checks.

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 free-form US addresses but does not explicitly mention when not to use it or alternatives. Given sibling tools like address_validate_batch, explicit guidance would be beneficial, but it's not present. The context is clear enough that an agent might infer it's for single address validation.

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 disclose read-only, idempotent, and non-destructive behavior. The description adds valuable context with 'Per-item errors are returned inline', indicating that failures do not fail the entire batch. This goes beyond what the schema or annotations state.

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, front-loaded with the primary action and scope. The second sentence adds useful behavioral detail. No filler or 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 no output schema, the description should explain what a successful response looks like (e.g., standardized address, validation status). It only mentions per-item errors, leaving the success return format unspecified. For a simple validation tool, this is a notable 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% for the single parameter, which already describes 'Up to 50 free-form US addresses.' The tool description repeats this information without adding new meaning. Baseline 3 is appropriate since the schema handles the param 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?

The description clearly states the action ('Validate'), the resource ('US addresses'), and the batch scope ('up to 50 in one request'). This distinguishes it from sibling tools like address_validate, which presumably handles a single address.

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 batch usage through 'up to 50' and 'in one request', but it does not explicitly state when to choose this over address_validate or mention alternatives. The context is clear, but no explicit when-not or alternative guidance is provided.

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

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

The description adds valuable behavioral details beyond the annotations: it mentions Luhn-checking, that the PAN is never echoed, and that it is PCI-safe. These security/privacy practices are not captured in the readOnlyHint or other annotations, giving the agent useful context about how input is handled.

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 tool's purpose, then lists inputs and outputs compactly. Every sentence carries useful information without 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?

The description covers the main purpose, input requirements, and explicit return fields (scheme, card_type, brand, issuer_bank, country, risk_band). With a simple tool and 100% schema coverage, the description is sufficiently complete, though it could mention edge-case behavior like errors for invalid BINs.

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%: both `card_or_bin` and `use_binlist_fallback` already have clear descriptions. The description does not add much beyond restating the input format for `card_or_bin` and doesn't mention the fallback parameter at all. With full schema coverage, 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 uses a specific verb 'Identify' with a clear resource ('card BIN') and enumerates the exact outputs (issuing bank, scheme, card type, country). It distinguishes from sibling tools by uniquely addressing card BIN/PAN lookup among address, phone, company, and other lookup 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 clearly states the accepted input types (6-8 digit BIN or full PAN) and what the tool returns, providing adequate context for when to use it. It does not explicitly mention alternatives or exclusions, but no sibling tool handles card BINs, so confusion is unlikely.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the 'business day' concept, which implies holiday/weekend handling, but doesn't detail edge cases or the exact holiday calendar used.

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, front-loaded sentence with no redundant 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?

For a simple date calculation tool with safe annotations, the description covers the core functionality and return value. However, it omits details about negative days, holiday calendar specifics, and behavior when the start date falls on a weekend, which are relevant for business-day calculations.

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 50%: 'date' is described but 'days' is not. The description maps 'N' to the days parameter and 'date' to the date parameter, but adds no additional details like valid ranges, negative values, or zero-day behavior.

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 action (add) and the resource (business days to a date), and mentions the return value. It does not explicitly distinguish itself from sibling calendar tools like calendar_is_business_day or calendar_holidays, but the purpose is 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?

There is no guidance on when to use this tool versus the calendar siblings, nor any exclusions or alternative recommendations. It simply describes the operation.

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, covering the safety profile. The description adds a valuable behavioral detail: holidays are according to 'OPM rules' and include 'observed dates,' which is not apparent from the schema or annotations. It does not fully detail return format, but the burden is lowered by the strong 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, information-dense sentence. It leads with the action and resource, then adds a specific rule detail, with no wasted words or 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 simple tool with one optional parameter and no output schema, this description is complete. It states what is returned (federal holidays), the scope (for a year), and a key rule (OPM observed dates). No further context is needed to 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 coverage is 0%, so the description must clarify the parameter. The phrase 'for a year' directly indicates that the year parameter determines the output. Although it does not state that the year is optional or define a range, it provides essential meaning beyond the bare schema property name.

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 'List' and clearly identifies the resource: 'US federal holidays for a year.' It also mentions 'including observed dates per OPM rules,' which adds scope and distinguishes it from sibling tools like calendar_business_days_add and calendar_is_business_day.

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 clearly indicates this tool is for obtaining federal holiday listings, providing clear context for when to use it. It does not explicitly state exclusions or name alternative tools, but the focus on holidays and OPM rules makes the appropriate use case unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the business-day definition (weekday and not federal holiday), which is useful. However, it does not disclose any nuances such as observed holidays, timezone assumptions, or default behavior on weekends, so it adds moderate value beyond 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?

One succinct sentence that fully defines the tool's purpose and the meaning of 'business day.' No word wasted, 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?

For a simple read-only predicate with one parameter and no output schema, the description is complete. It explains the input, the rule, and the scope (US federal holidays). The rich annotations further cover safety and idempotency, making this adequate for an agent to 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?

The single parameter 'date' has 100% schema coverage with a descriptive type ('ISO date YYYY-MM-DD'). The description does not add any semantic detail beyond the schema, 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 uses a specific verb ('Check') and clear resource ('a US date') with an explicit definition of business day ('weekday and not a federal holiday'). It distinguishes itself from siblings like calendar_business_days_add and calendar_holidays by focusing on checking a single date rather than arithmetic or listing.

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 clearly implies when to use this tool: to test whether a specific date is a US business day. It does not explicitly mention alternatives or exclusions, but the context of sibling tools (e.g., calendar_business_days_add) makes the use case apparent. Lacks explicit 'use instead of' guidance which would merit a 5.

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 behavioral context: live EDGAR lookup, item-code classification, and output composition (score, theme, action_hint). This goes beyond the annotations without contradicting 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 a single, dense sentence that packs all essential information without filler. It is front-loaded with the tool's core identity. Slightly long but every clause 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?

With no output schema, the description adequately explains the return values: change-velocity score (0-100), dominant theme, and buyer-shaped action_hint. It also mentions the data source. It could specify the structure of returned data in more detail, but it covers the key aspects.

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 only 40% (domain and ticker have descriptions). The description compensates somewhat by explaining buyer_profile and its enum values, but limit and window_days rely on their names and defaults. It does not fully compensate for the low 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 states a specific action: pulls SEC 8-K filings live from EDGAR, classifies item codes into change categories, and returns a score/theme/action_hint. It clearly differentiates from siblings like company_changes or company_signal by focusing on a change-signal envelope for public companies.

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 clear context: for public company change signals, with buyer_profile indicating use cases (sales_outreach, recruiter, etc.). It does not explicitly state when not to use it or name alternatives, but the context is strong enough to guide selection.

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 establish read-only, idempotent, non-destructive behavior. The description adds value by disclosing that results are time-ordered and enumerates the types of changes (status flips, acquisitions, renames), going beyond the annotations. It does not mention pagination or rate limits, but the core behavioral traits are covered.

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 the first sentence immediately stating the domain, the second detailing functionality, and the third providing use-case context. Every sentence earns its place 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?

For a list tool with 7 parameters and no output schema, the description conveys the core purpose, filter options, and typical use cases. It lacks explicit information about response structure or pagination, but the essence of the tool is well captured. A bit more detail about return fields would make it fully complete.

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

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

Schema description coverage is 71%, and the description renames the same filters (since-date, LEI, change_type, country) without adding new meaning. The 'domain' parameter is not mentioned in the description, and page/per_page are left undocumented in both schema and description. 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 'time-ordered entity changes' with specific examples like 'status flips, parent acquisitions, renames,' making its purpose obvious. It distinguishes itself from sibling lookup tools by focusing on change monitoring rather than current state.

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

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

The description provides clear context for use: 'Critical for continuous KYC and M&A monitoring.' It does not explicitly mention alternatives or when not to use it, but the use case is well-defined. Lacks explicit exclusions, so not a 5.

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, covering the safety profile. The description adds the useful behavioral detail that leading zeros are accepted and normalized, with an explicit example. This goes beyond the annotations by clarifying input handling.

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 primary action and resource. Every sentence contributes useful information: what the tool does and how input is normalized. No fluff or 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?

The tool has no output schema, so the description should explain what the return value looks like. It says 'unified company profile' but does not enumerate any fields or structure. For a simple lookup tool with rich annotations and schema, this is a minor gap, making it adequate but not fully 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 a description for the 'cik' parameter that includes the same leading-zeros example. The tool description repeats this example, adding marginal value ('Apple' as a concrete instance). Baseline 3 is appropriate because the schema already documents the parameter fully.

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 language: 'Resolve a SEC EDGAR Central Index Key (CIK) to a unified company profile.' It clearly states the input (CIK) and the output (unified company profile), and provides an illustrative example (Apple). This distinguishes it from siblings like company_search or company_enrich, which have different purposes.

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

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

The description implicitly tells when to use this tool: when you have a CIK and want a unified company profile. It does not explicitly contrast with sibling tools (e.g., company_search, company_lookup_auto), nor does it mention when not to use it, but the context is clear enough for an agent to infer the appropriate use case.

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 safety is covered. The description adds context about using a 'loaded curated company profile set' but doesn't disclose output format, error behavior, or state requirements beyond that.

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?

A single, front-loaded sentence communicates the core action and data source with no filler. It is highly concise and easily parsed.

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

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

For a single-parameter tool with strong annotations, the description is adequate but ambiguous about what 'classify' means or what output to expect. Without an output schema, the description could better clarify the classification result.

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 fully describes the 'url' parameter with an example, so description adds no extra semantics beyond confirming the input is a domain. Baseline of 3 applies because schema coverage is 100%.

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 the tool classifies a domain using a curated company profile set. The verb 'classify' and resource 'domain' are specific, though it doesn't explicitly distinguish from sibling tools like company_industry or company_domain.

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?

No guidance on when to use this tool versus alternatives, and no mention of prerequisites. The phrase 'loaded curated company profile set' implies a dependency but doesn't clarify how or when the tool should be invoked.

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, idempotent, and non-destructive behavior. The description adds the demo mode qualifier, which is useful, but does not describe return format, error handling, or domain normalization.

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?

One concise sentence states the core function and adds a relevant qualifier about demo mode. Every word earns its place, and the description is front-loaded with the primary action.

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

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

For a single-parameter read-only lookup, the description is adequate but lacks details about what the profile contains or how demo mode affects results. Given the many sibling tools, additional differentiation would improve completeness.

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

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

The schema has 100% coverage with a parameter description ('Company domain or URL.'). The tool description adds no meaningful parameter semantics beyond what the schema already states.

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 verb 'Return' with resource 'company profile by domain' clearly states the function. It distinguishes from search/enrich siblings by specifying domain-based lookup, but does not explicitly name alternatives or define what a profile includes.

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?

No guidance is provided on when to choose this over company_enrich, company_search, or company_lookup_auto. The demo mode note is a behavioral hint, not a usage directive.

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 behavior. The description adds useful context beyond annotations: 'bounded request' (the 10-item max) and 'Demo mode' with selected sample domains. This clarifies limits not captured elsewhere, though error handling for invalid domains remains unspecified.

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 of minimal length: the first states the function, the second adds a demo-mode caveat. Everything included is relevant and there is no redundant or filler content.

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

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

For a tool with one fully described parameter, rich annotations, and no output schema, the description is adequately complete for selection and invocation. It lacks detail on error behavior or partial results, but these are minor given the simple interface.

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% for the single parameter 'domains', with an example and note about comma-separated strings. The description merely repeats 'domain' without adding further semantics, so the baseline of 3 applies.

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?

Uses a specific verb 'Return' with a clear resource 'multiple company profiles', scoped by 'domain'. The phrase 'in one bounded request' distinguishes it from single-domain tools like company_domain and other batch operations.

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

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

The description implies a batch use case ('multiple company profiles', 'one bounded request') but never explicitly contrasts with alternatives such as company_domain for a single lookup or company_lookup_batch for name-based matches. No when-not-to-use guidance is provided.

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 behavior. The description adds valuable context by disclosing the actual data categories included and that SEC filings are conditional on public status, which is beyond the schema and 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, highly informative sentence that is front-loaded with the core action ('one-call company enrichment') and then lists the specific data elements. Every word earns its place 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?

Although there is no output schema, the description gives a clear high-level summary of the expected return contents (identity, DNS, tech stack, SEC filings, cyber risk score). For an aggregate enrichment tool, this adequately sets expectations, though it could provide more detail on the structure of the response.

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 schema fully covers the single parameter 'domain' with a clear description and example, giving 100% coverage. The description does not add any additional meaning beyond what the schema already provides, so the baseline 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's purpose with a specific verb ('one-call enrichment') and enumerates the exact resources returned (identity, DNS, tech stack, SEC filings, cyber risk score). This distinguishes it from the many sibling tools that cover only one of these aspects.

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 phrase 'one-call' indicates the tool should be used when multiple data categories are needed in a single request, differentiating it from individual data tools. However, it does not explicitly mention alternatives or situations where separate calls would be preferable.

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 context with 'loaded curated' profiles, indicating the search operates on a specific pre-filtered dataset, and 'category, or description signals' shows it runs on semantic signals, which is useful beyond the raw 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, front-loaded sentence that immediately starts with the verb 'Search' and communicates the essential purpose without unnecessary words. It is concise and well-structured.

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 single-parameter search tool, the description covers the core functionality and data scope. It lacks explicit return-value details, but since there is no output schema and the tool is straightforward, this is acceptable. The mention of 'loaded curated' adds important context about data limitations.

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 a basic description of the 'industry' parameter. The tool description enriches this by stating the search also covers category and description signals, giving the agent a broader understanding of what qualifies as a valid query value, though it may slightly conflict with the schema's simpler definition.

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

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

The description clearly states the tool 'searches loaded curated company profiles by industry, category, or description signals,' which specifies the verb (search), resource (company profiles), and search criteria. This distinguishes it from sibling tools like company_search or company_enrich by focusing on industry/category/description signals.

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 through the search criteria, but it does not explicitly compare to alternatives or state when not to use it. It would benefit from mentioning that other company search tools cover different query types (e.g., name, domain).

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is safe. The description adds the scope of the response but does not disclose additional behaviors such as response size, pagination, rate limits, or any latency caveats beyond what's in the schema for include_filings.

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—two short sentences with no filler. It front-loads the key value proposition and lists the main components efficiently.

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

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

For a complex 'mega-endpoint' with 10 parameters and no output schema, the description is under-specified. It does not explain how to provide a company identifier, what the response shape looks like, or any caveats (e.g., filings only for public companies, latency). The tagline 'everything we know' overpromises without operational details.

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?

Only 1 of 10 parameters has a schema description (include_filings), and the tool description does not explain any parameters or how the identifier fields (lei, domain, ticker) relate to each other. The description's list of included components loosely maps to the boolean flags, but does not clarify defaults or selection logic, leaving a significant semantics gap.

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 identifies the tool as a single-call aggregate endpoint and enumerates its components (profile, hierarchy, network, timeline, peer benchmark), clearly distinguishing it from narrower sibling tools like company_enrich or company_peer_comparison. However, it lacks an explicit verb phrase like 'retrieve' or 'get', relying on the title and tagline to convey the action.

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 this is the go-to call for a comprehensive company view ('everything we know'), but it does not explicitly state when to choose this over alternatives or any exclusions or prerequisites. No alternative tools are named, and there is no guidance on trade-offs like latency or 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 and idempotent behavior, lowering the bar. The description adds useful context by disclosing that resolution.matched_on is returned so the caller can confirm which identifier type was used, going beyond the schema and 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 only two sentences, front-loaded with the core action and followed by valuable return behavior information. Every word earns its place 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?

For a simple one-parameter lookup with rich annotations and no output schema, the description covers purpose, accepted inputs, and a key return field. It is adequate for typical use, though it could have briefly mentioned the broader resolution object or error behavior for full completeness.

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

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

Schema description coverage is 100% and already provides detailed heuristics for each accepted identifier type. The description merely lists the same types without adding new meaning, so it meets the baseline without enhancing 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 a specific verb ('Auto-detect and route') and clearly states the resource and accepted identifier types (LEI, CIK, domain, email, ticker, exact name). It distinguishes itself from siblings like company_cik or company_lookup_batch by emphasizing type auto-detection for a single lookup.

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

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

The 'Auto-detect identifier type' phrasing clearly implies use when the identifier type is unknown, which distinguishes it from type-specific tools. However, it does not explicitly name alternative tools or state when not to use it, stopping short of full 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 convey read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by stating that each result preserves the original input for join-back, which is not implied by the annotations or schema. This provides useful insight into the response structure, though it doesn't cover all edge-case behaviors.

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, each earning its place. The first states the core function and limit; the second adds a critical join-back detail. No filler or 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 single-parameter batch tool with no output schema, the description covers the essential aspects: identifier types, batch size, single request, and result join-back. It lacks details on error handling or partial success behavior, but given the simplicity and good annotations, it 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?

With 0% schema description coverage, the description carries the burden of explaining the parameter. It enumerates the allowed identifier types (domain, LEI, ticker, name), which directly corresponds to the schema enum, and explains that they can be mixed. This adds semantic value beyond the bare schema, though it doesn't describe the exact object structure (type/value) in prose.

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 a specific verb ('Resolve') and resource ('up to 50 mixed identifiers') with clear enumeration (domain, LEI, ticker, name). It distinguishes itself from siblings by highlighting the batch capability and the mixed-type support, making the tool's purpose unmistakable.

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 clearly indicates the tool is for batch resolution (up to 50 items in a single POST), which implies the use case of processing multiple identifiers at once. However, it does not explicitly mention when not to use it or point to alternatives like single-lookup tools, so it stops short of full 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so safety profile is covered. The description adds meaningful behavioral context: it walks a specific hierarchy (GLEIF ultimate-parent), returns all entities at that root, and excludes pension/retirement trusts by default. This goes beyond annotations by clarifying scope and default filtering behavior. A small gap: it doesn't mention whether this is paginated or how many results may be returned, but with openWorldHint and no output schema, it's reasonably transparent.

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: the first states the core action and outcome, the second adds a key default behavior. No filler, no repetition of schema or annotations, and it front-loads the 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?

For a read-only lookup with annotations covering safety and idempotency, the description covers the main entity-relationship semantics (walk ultimate-parent hierarchy, return same-root entities, default exclusion). No output schema, but the purpose is clear and the parameters are mostly documented. A minor gap is not explaining pagination behavior or result limits, but this is a moderate-complexity tool and the description is adequate.

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 60%, with 3 of 5 params described (lei, domain, per_page) and 2 minimal (page, include_pension_trusts). The description adds important meaning for include_pension_trusts by stating the default exclusion of pension/retirement trusts, which directly explains the parameter's role. It also clarifies 'lei' and 'domain' are resolution paths, but the schema already indicates that. It doesn't fully explain 'page' semantics, but the schema default and integer type give some clue. Overall, the description compensates for the schema gaps and adds value.

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

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

The description uses a specific verb ('Walk') and resource ('GLEIF ultimate-parent hierarchy') and clearly states the result: 'return every entity sharing the same conglomerate root.' It also distinguishes itself from sibling tools like company_enrich (single-entity lookup) and company_peer_comparison by focusing on the corporate family/root hierarchy.

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 when to use this tool: when you need the full ultimate-parent hierarchy ('every entity sharing the same conglomerate root'), which is distinct from other company tools. It doesn't explicitly name alternatives or exclusions (e.g., 'for single-entity lookup use company_enrich'), but the context of the goal and siblings makes the use case clear. The 'Excludes pension/retirement trusts by default' notes a default behavior that guides expected use.

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 no additional behavioral context such as data freshness, rate limits, or return format, providing no value 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 a single sentence that is front-loaded with the verb and resource. No wasted words or 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 simple single-parameter lookup tool with strong annotations and full schema coverage, the description is mostly adequate. However, without an output schema, it leaves the contents of 'identity profile' unspecified and doesn't point to alternative tools, so a slight improvement could be made.

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 'ein' parameter, with an example provided. The tool description merely restates 'by EIN' without adding additional semantic meaning beyond the schema already provides, 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?

Description uses specific verb 'Return' with clear resource 'nonprofit identity profile' and input 'EIN'. This distinguishes it from sibling tools like company_nonprofit_search (likely searching by name or criteria) and company_enrich (which may use other identifiers).

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention when to use EIN-based lookup vs other company tools, nor does it include any exclusions or preconditions.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds only the search dimensions, which are more parameter semantics than behavior. It does not disclose result format, pagination, or any additional operational behavior, but it is consistent with the annotations and adds a little 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 a single, front-loaded sentence that conveys the tool's purpose and key search dimensions without any redundant content. Every word earns its place, and it is appropriately sized for a straightforward search tool.

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 tool with only two parameters and comprehensive annotations, the description covers the essential purpose and search fields. It does not explain return values or pagination, but given the simplicity and high schema coverage, these omissions are acceptable. The absence of explicit differentiation from the sibling company_nonprofit_ein is a minor gap, but the overall context is sufficient.

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

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

Schema coverage is 100% for both parameters, giving a baseline of 3. The description goes beyond the schema by clarifying that the 'q' parameter can represent a name, category, EIN, or state, which adds meaningful interpretation beyond the schema's generic 'Search query' example. This extra context justifies a score above baseline.

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 the specific verb 'Search' and clearly identifies the resource as 'nonprofit identity profiles', distinguishing it from sibling tools like company_search and company_nonprofit_ein. It also lists searchable dimensions (name, category, EIN, state), making the tool's 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 implies when to use the tool by listing searchable fields (name, category, EIN, state), but it does not explicitly mention alternatives, exclusions, or prerequisites. For a search tool, this level of context is minimal but not absent, so it earns a borderline score.

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 disclose read-only, idempotent, and non-destructive behavior. The description adds valuable context about the output's analytical dimensions, which helps the agent set expectations. It does not cover edge cases like empty peer sets or failure modes, but given the annotations, the added context is sufficient.

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 sentence that starts with the action and lists the key outputs without filler. Every phrase adds informational value, making it both concise and informative.

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

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

With no output schema, the description takes on the burden of explaining what the tool returns, and it does so by listing the specific peer-set analytics. It does not describe the response structure or peer-selection criteria in depth, but for a benchmarking tool with clear annotations, this is a solid level of completeness.

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

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

The input schema has descriptions for lei, domain, and ticker (75% coverage). The description does not elaborate on these parameters, nor does it explain the 'scope' enum values beyond the default 'industry_country' implied by 'same-industry/same-country'. The semantics are mostly left to the schema, and the missing scope description is not compensated for, though the enum values are fairly self-explanatory.

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 identifies the tool's verb ('Benchmark') and resource ('a company'), and specifies the peer comparison context with concrete output dimensions (employee distribution, jurisdiction mix, founding-decade histogram, rank). This strongly differentiates it from sibling tools like company_enrich or company_industry.

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 establishes a clear use case: benchmarking a company against peers in the same industry/country. It implies when to use this tool, but does not explicitly mention alternatives or exclusion cases (e.g., 'if you only need one metric, use X'). Still, the context is unambiguous enough for an agent to select it over unrelated 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?

The description adds behavioral context beyond the annotations: it warns that registration numbers aren't globally unique and that country disambiguation is necessary. This clarifies result ambiguity, which readOnlyHint/idempotentHint do not cover. 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 two sentences with front-loaded purpose and a practical usage tip. Every word earns its place; no filler.

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 resolution tool, the description is complete: it specifies the input (registration number), the required disambiguation (country), and the output (company profile). The schema fully documents parameters, and annotations cover safety/idempotency, so no critical 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?

All three parameters are described in the schema (100% coverage), so the baseline is 3. The description enhances the semantics by explaining why the country parameter matters ('regnums aren't globally unique'), which is not evident from the schema alone. It also provides a concrete example (Stripe's Delaware file number) in the schema 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?

The description uses the verb 'Resolve' and clearly identifies the resource ('registry-assigned registration number ... to a company profile'). It provides concrete examples (Companies House, Delaware file number, Handelsregisternummer), which distinguishes it from sibling lookup tools that operate on domains or 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 clearly indicates this tool is for when you have a registry-assigned registration number. It also instructs to pass country= for disambiguation because registration numbers aren't globally unique. However, it does not explicitly name alternatives or exclusion criteria, so it stops short of complete when/when-not 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by noting the dataset is curated and that demo mode restricts queries to selected samples, which helps set expectations.

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—two short sentences—with no fluff. It front-loads the core purpose with the verb 'Search' and adds a necessary note about demo mode, making every word count.

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 search tool with a single parameter and good annotations, the description covers the essential aspects: what it searches, the nature of the dataset, and an operational caveat (demo mode). It could elaborate on return formats, but the simplicity and available annotations make this 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?

The schema describes 'q' with an example but the description enriches the meaning by clarifying that 'q' can be a name, domain, industry, or ticker. This goes beyond the basic schema description and helps the agent construct effective queries.

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 ('Search') and a distinct resource ('loaded curated company profiles'), explicitly listing the queryable fields (name, domain, industry, or ticker). This clearly distinguishes it from siblings like company_lookup_auto or company_enrich by emphasizing the curated dataset 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?

The description provides clear context for when to use the tool (searching within curated company profiles) and mentions demo mode limitations. However, it does not explicitly state when not to use it or name alternative tools for other purposes, though the context strongly implies its role among 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 cover read-only, idempotent, open-world, non-destructive. The description adds meaningful behavioral context: it joins identity, SEC filings, DNS/DMARC, WHOIS, and hiring signals; calculates an explainable score tuned by buyer profile; and returns specific outputs. This enriches the behavioral profile beyond 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?

One densely packed sentence that efficiently conveys purpose, inputs, methodology, and outputs without fluff. Every clause adds information, though it could be slightly restructured for readability.

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 tool without output schema, the description lists all major return components (overall score, tier, verdict, six sub-scores, tech-stack hint, SEC activity summary). It also mentions the join logic and profile tuning, providing a solid understanding of what the tool computes. Some edge cases like domain/ticker precedence are left to the schema, which is acceptable.

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 already documents all 4 parameters with 100% coverage, including enums and defaults. The description reinforces the buyer_profile concept and the SEC filings dependency but doesn't add new parameter details 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?

Clearly states it produces a composite B2B buyer-signal score (0-100) for a company, and differentiates from related tools like funding_signal or hiring_signal by combining multiple signal types and buyer profile tuning.

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?

Description implies usage for B2B buyer signaling with a specific buyer profile, clearly connecting to the buyer_profiles sibling tools, but does not explicitly name alternatives or exclusions. The context is clear enough for an agent to select this over single-signal 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral detail about the scope (3.3M entities), the facets computed, and the inclusion of hierarchy/data-quality coverage, going 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?

Two concise sentences that front-load the core purpose and then list facets and filters. Every word earns its place; no redundancy or filler.

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

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

Given the tool's simplicity, the description covers the main behavior and available filters. There is no output schema, but the description states that aggregate counts are returned. It could specify the exact return structure, but this is not critical for an aggregation tool with optional parameters.

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 schema provides 100% description coverage for all parameters. The description reinforces which filter parameters exist (country, jurisdiction, industry, naics) but adds no additional semantic detail beyond the schema. Top_n and its range are only in 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 aggregate counts from a specific resource (the 3.3M-entity registry) and enumerates the grouping dimensions. It distinguishes itself from sibling lookup/enrichment tools by focusing on aggregations rather than individual records.

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 statistical overviews and mentions filtering by parameters, giving context for when to call it. However, it does not explicitly state exclusions or name alternatives, so it falls short of full 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the basic safety profile. The description adds 'loaded curated', which hints at a pre-processed or cached profile, but does not disclose any additional behavioral traits such as rate limits, data freshness, or error conditions. This is acceptable given the strong annotation coverage.

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, concise sentence that conveys the essential purpose without redundant words. It is front-loaded with the action ('Return') and resource, making it easy to parse quickly.

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 single-parameter lookup tool with strong annotations and no output schema, the description is sufficient for an agent to know what input to provide and what kind of output to expect (a curated company profile). The lack of explicit sibling differentiation is a minor gap, but the tool is straightforward enough that this does not impede correctness.

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 already provides a clear description for the only parameter (ticker: 'Ticker symbol, for example NVDA.'), with 100% schema coverage. The description's phrase 'by public ticker' aligns with the schema but adds no new semantic detail, so a 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 verb ('Return') and resource ('loaded curated company profile'), scoped by 'public ticker'. It is specific enough to distinguish from many of the 80+ sibling tools, though it does not explicitly mention how it differs from similar company-related tools like company_enrich or equities_ticker.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or comparative context with any sibling tools, leaving the agent to infer suitability solely from the name and description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful context beyond annotations by specifying the type of events returned (founding year, SEC rebrands, parent disclosures) and that the list is chronological. It does not contradict annotations and provides useful behavioral insight into the output.

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, front-loaded sentence that packs in the core purpose and examples without any fluff. Every clause adds value, making it highly concise and well structured.

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 read-only lookup tool with 3 optional parameters and no output schema, the description gives a solid sense of what is returned (chronological list, specific event types). It does not explain parameter precedence or behavior when no params are provided, but this is a minor gap given the simplicity of the tool and the annotations. Overall, it is sufficiently complete 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 description coverage is 100%, with each parameter (lei, domain, ticker) described as 'Resolve subject by ...'. The description does not add further parameter semantics or clarify precedence when multiple identifiers are provided. Baseline of 3 is appropriate since the schema already documents each parameter.

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 'Chronological lifecycle event list for any company' with concrete examples (founding year, SEC former-name rebrand events, current status, parent disclosures). This distinguishes it from sibling tools like company_enrich or company_registration, which focus on current data rather than a timeline.

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 when to use the tool (when you need lifecycle events), but it does not explicitly state alternatives or exclusions. For example, it does not say 'use company_enrich for current details' or 'avoid this if you only need current status'. The usage context is implied rather than explicit, so it falls short of strong 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: it lists the specific data sources (OFAC SDN, SEC enforcement), the output components (score, tier, decision_hint with enumerated values, critical flags), and the tuning by buyer_profile. It also adds the critical scope limitation ('decision-support only'). This goes well beyond the annotations without contradicting them, so a 5 is appropriate.

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 well-structured: 3 sentences, each with a distinct purpose (function/outputs, tuning, scope). It is front-loaded with the main verb and resource, and every sentence adds value without fluff or 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 there is no output schema, the description does a good job explaining return values (score, tier, decision_hint with enumerations, critical flags) and the input context (company resolution via domain/ticker/company, buyer_profile tuning). It is complete for a snapshot tool, but could be slightly richer about data freshness or how the score is derived. Still, it is sufficient, so a 4.

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 75% (domain, ticker, company have descriptions; buyer_profile has an enum but no description). The description mentions 'Tuned by buyer profile' and lists the profile values, but this largely duplicates schema info. It does not add meaning to domain/ticker/company beyond what the schema already states about resolving canonical names. Since baseline for high coverage is 3, and the description provides minimal added param context, a 3 is warranted.

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 function: 'Compliance-status snapshot for a company: screens against Treasury OFAC SDN entries and SEC enforcement actions, and returns a 0-100 compliance score, tier, decision_hint, and critical flags.' It uses a specific verb ('screens') and resource ('compliance status'), and distinguishes from siblings like sanctions_search (which is a raw search) and company_signal (a general signal) by focusing on compliance scoring and decision support.

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

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

The description provides clear context for use: 'Tuned by buyer profile' and 'SCOPE: decision-support only — does not replace formal KYC or licensed sanctions screening.' This gives a when-not-to-use warning (not for formal KYC) but does not explicitly name alternative tools, such as sanctions_search or intel_compliance_profiles. Thus it has clear context but no explicit exclusions or alternatives, meriting a 4.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld). The description adds meaningful behavioral context: it joins live SEC EDGAR filings (implying network calls and potential latency), defines the score scale (0-100, higher = lower risk), and explains the decision_hint mapping to AR/AP actions. It does not discuss missing-data scenarios, but the incremental transparency is solid.

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, front-loaded with purpose, then data sources and outputs. Every clause adds value, with no repetition of schema/annotations. The description is dense but 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?

The description covers the core purpose, inputs (implied), and outputs (score, tier, decision_hint) even without an output schema. It is complete for a read-only composite risk tool, though it could improve by specifying parameter semantics and edge-case behavior. Overall, it gives an agent enough to invoke the tool correctly for its primary use.

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

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

Schema coverage is only 50% (domain and ticker have descriptions). The description vaguely references risk_profile ('four risk profiles') but does not explain what each profile means or how to choose. include_filings is not mentioned at all, despite the description emphasizing SEC EDGAR filings. The description fails to compensate for the undocumented 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 a specific verb and resource: computing a B2B counterparty-risk composite to decide whether to extend terms. It enumerates the data sources (identity, SEC EDGAR, DNS/DMARC, WHOIS) and the outputs (score, tier, decision_hint), making it distinct from sibling tools like cyber_risk or company_enrich.

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 a clear use case ('should we extend terms to this company?') and mentions four risk profiles for different underwriting postures, implying how to adapt usage. It does not explicitly name alternative tools or when-not-to-use scenarios, but the context is concrete enough for an agent to select it for credit 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context: the scale interpretation ('higher = lower risk'), the exact six sub-score categories, critical flags, recommended actions, and the crucial scope limitation (published DNS only). This goes well beyond what annotations provide and gives the agent a clear model of the tool's behavior and output.

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, front-loaded with the core purpose and output, and a second sentence for scope. Every clause adds value: the sub-score enumeration is compact but informative, and the SCOPE line prevents misuse. No filler or 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?

The tool has no output schema, so the description must explain return values, which it does thoroughly (score, sub-scores, flags, actions). It also covers input tuning (buyer_profile) and scope boundaries. For a read-only scoring tool with two parameters, this is complete enough 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?

The schema describes the 'domain' parameter but not 'buyer_profile'. The description adds meaning to 'buyer_profile' by stating the tool is 'Tuned by buyer profile', which explains its role in adjusting the score. For 'domain', the schema description suffices. With 50% schema coverage, the description partially compensates but could have elaborated on how buyer_profile affects results more concretely.

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 a specific verb-resource pair ('DNS-hygiene + tech-stack-exposure surface for a domain') and clearly distinguishes the tool from siblings by detailing the composite 0-100 cyber score, six sub-scores, and explicit scope exclusions. This is much more specific than a generic label and differentiates it from DNS-only or tech-stack-only 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 implies when to use this tool (for a domain-level cyber risk assessment) and explicitly states what it does not do ('no port scans, breach lookups, or CVE matching'), which helps rule out alternatives. However, it never names sibling tools like dns_lookup or tech_stack as alternatives, so the guidance is contextually clear but lacks explicit when-not-to-use references.

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?

With annotations already covering the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the bar is lower, and the description adds useful context beyond them: the external source (crt.sh/CT logs), the recency constraint, and the deduplicated subdomain-collection behavior across all CT entries. Nothing in the description contradicts the read-only, non-destructive, idempotent nature of 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 source and return behavior, with use cases placed last for scannability. Minor redundancy exists between "Recent SSL certificates" and "Returns recent certs" in consecutive sentences, preventing a perfect score, but every sentence otherwise 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?

Since there is no output schema, the description correctly takes responsibility for return values and covers the key elements: certs with issuer and expiry, plus the deduplicated subdomain list. Combined with full annotation coverage, this is fairly complete for a simple 2-parameter read-only tool, though it leaves gaps around what "recent" means, whether 'domain' matches base domain or subdomains, and how 'limit' applies.

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 0%, so the description carries the full burden for parameter meaning. The 'domain' parameter is only implied via the title and the "hostname discovery" use case, and the 'limit' parameter (default 20, max 100) is never mentioned — the agent receives no explanation of how limit affects the returned cert count or whether the subdomain list is subject to it.

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 opens with a specific noun phrase identifying the resource — "Recent SSL certificates from Certificate Transparency logs (crt.sh)" — followed by a concrete statement of returns: "Returns recent certs with issuer + expiry, plus the deduped subdomain list." This clearly distinguishes dns_certificates from sibling DNS tools (dns_lookup, dns_history, dns_tls) by anchoring on CT-log certificate data and the unique subdomain-discovery output.

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 names three concrete, valid use cases: "shadow-IT detection, sales-intel hostname discovery, and phishing-cert monitoring," giving an agent clear situational context for when to select this tool. However, it does not mention when-not-to-use it or name alternative sibling tools, so it stops short of the explicit guidance required for a 5.

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, covering safety. The description adds meaningful behavioral context beyond these: it is purely analytical with no DNS query, and it discloses that it flags is_likely_typosquat and is_likely_lookalike with drivers. It does not detail output structure or edge cases, but the annotations lower the bar.

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 main purpose, and every clause adds value (algorithms, flags, no-DNS clarification). There is zero fluff or repetition of schema details.

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 no output schema, the description takes responsibility for explaining return behavior; it mentions key flags and drivers but not the full result structure. Given the tool's simple 2-parameter nature and strong annotations, this is sufficiently complete for an agent to use 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%, with clear descriptions for both parameters (reference as known-good, target as suspect). The description reinforces these roles but adds no new format, syntax, or constraints beyond the schema. 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 compares a target domain against a reference for phishing/typosquatting/lookalike detection, with specific verb 'Compare' and resource 'domain'. It also distinguishes from sibling DNS tools by explicitly noting 'no DNS query', making the purpose unambiguous.

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

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

It provides clear context (compare two domains for typosquatting) and implicitly excludes DNS queries by stating 'Pure analytical comparison — no DNS query'. However, it does not explicitly name alternative tools like dns_lookup or provide when-not-to-use guidance, so it falls short of a 5.

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, idempotent, and open-world behavior. The description adds meaningful context beyond this by explaining that data accumulates from user lookups, is snapshot-on-query, and is not a global feed, which clarifies data freshness and coverage limits.

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 four sentences, each adding distinct information: the operation, return format, use cases, and limitations. It is front-loaded with the primary function and contains no filler or redundant wording.

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 no output schema, the description adequately explains the return tuple and the data's temporal scope, and it clearly states the data source limitation. It doesn't detail how limit_per_type affects results or domain format, but overall it provides sufficient context for a read-only query 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 only 33%, with only record_type documented. The description mentions record_type implicitly but does not clarify the semantics of domain or limit_per_type, which are otherwise undocumented. Given the low coverage, the description fails to compensate, leaving significant parameter ambiguity.

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 every DNS record tuple seen for a domain, with specific output fields (record_type, value, first_seen, last_seen, observation_count). It distinguishes itself from active DNS lookup by being a passive snapshot-on-query view, contrasting with sibling tools like dns_lookup.

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

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

It provides concrete use cases such as detecting when A records moved or recovering historical NS/MX values, and warns that it's not a global feed. However, it doesn't explicitly mention when not to use it or name alternatives, so it lacks explicit exclusion 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=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds value by disclosing the exact set of record types the tool can resolve, which is a behavioral detail not present in the annotations. It does not describe caching or failure behavior, but for a simple lookup this is sufficient.

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, front-loaded sentence that uses an active verb and lists all supported record types in a compact manner. Every word earns its place, with no filler or 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?

The tool is simple: two parameters, no nested objects, no output schema. The description fully states the tool's purpose and capabilities. The schema covers the input requirements. No essential context is missing, especially given the read-only and idempotent annotations.

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 the baseline is 3. The description goes beyond the schema by explicitly enumerating the valid values for the 'types' parameter (A, AAAA, MX, etc.), which is more informative than the schema's generic 'comma-separated record types' description. This helps an agent understand exactly what the tool can return and how to filter.

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 the specific verb 'Resolve' and names the exact resource (DNS records for a domain) and enumerates all supported record types (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA). This clearly distinguishes it from sibling tools like dns_certificates, dns_history, or dns_whois, which focus on more specialized DNS data.

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

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

The description provides clear context: it is the general-purpose DNS record lookup tool. While it does not explicitly state when to avoid it in favor of siblings, the record-type enumeration and the tool's name make the intended use unambiguous. No exclusions are necessary for a tool like this.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool performs a 'subdomain-probe' and produces a 'health-verdict,' indicating active analysis beyond a simple lookup, which is useful 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?

Two sentences, no fluff. The first sentence efficiently enumerates the components in a scannable list, and the second provides workflow context, earning 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?

For a complex tool with no output schema, the description provides a high-level summary of what is included but omits details on output structure or how the 'health-verdict' is derived, leaving some gaps for an agent expecting richer guidance.

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

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

The schema has 0% description coverage for its three parameters. The description indirectly explains skip_whois and skip_subdomains via the mention of WHOIS and subdomain-probe, but does not elaborate on their behavior or the domain parameter beyond the obvious.

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 enumerates specific components (DNS, WHOIS, security, hosting, email-infrastructure, subdomain-probe, health-verdict) and positions it as a single-call aggregate, clearly differentiating it from specialized siblings like dns_lookup and dns_whois.

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?

It provides a clear use case ('Sales-intel and security-audit workflow') and implies using this when a comprehensive picture is needed, but it does not explicitly state when to prefer specialized siblings instead.

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=false, so safety is clear. The description adds valuable behavioral detail beyond annotations: it enumerates the input factors and describes the return format (band + contributing factors). This helps set expectations about the composite nature and output structure, though it stops short of disclosing data freshness or scoring thresholds.

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 long, front-loaded with the core value proposition, and every word earns its place. It efficiently communicates the scoring range, contributing inputs, output format, and intended use case without any 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?

For a single-parameter scoring tool with no output schema, the description covers the essential context: what the score means, what inputs are used, what the output contains, and the intended domain of use. It lacks explicit error scenarios or caveats, but given the simple input and strong annotations, the description is reasonably complete. A 4 is warranted.

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 0%, and the description does not explicitly explain the 'domain' parameter. However, the tool name and description make it obvious that 'domain' is the domain name to score. The description adds no format details (e.g., punycode, subdomain handling), so it only partially compensates for the missing schema description. A score of 3 reflects marginal added value.

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

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

The description clearly states that this tool computes a composite 0-100 reputation score and lists the exact factors combined (domain age, registrar tier, expiration window, security grade, NS diversity, hosting tier). It also distinguishes itself from sibling DNS tools by emphasizing that it returns a score and band rather than raw DNS records, and by mentioning its use case in fraud-screening pipelines.

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 the intended use ('Designed for fraud-screening pipelines'), giving clear context for when to use this tool. It does not explicitly name alternative tools or provide exclusion criteria, but the scoring/banding purpose contrasts well with sibling DNS lookup tools, making the context strong enough for a 4.

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 known. The description adds useful behavioral context: it performs a live TLS handshake, returns a grade, and surfaces specific findings like days-until-expiry, SAN list, self-signed detection, and 'CBC-mode cipher in use'. This goes beyond annotations without contradicting 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?

Two dense sentences, front-loaded with the core action and result, followed by specific outputs. No filler or redundant 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?

For a 2-parameter tool with no output schema, the description covers the main behavior and return items. It lacks failure-mode details (e.g., timeout, invalid domain, no cert), but overall it is adequate for a live TLS probe 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 0%, so the description must compensate. It mentions port implicitly via ':443' but does not explain that the port parameter is configurable with min/max bounds, nor does it describe the required domain parameter. The tool name and context make 'domain' obvious, but the description fails to fully bridge the gap left by the undocumented schema.

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

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

The description clearly states the tool's action: 'Open a TLS handshake on :443', specifies what it captures (cert, protocol version, cipher), and explains the output (grade A-F). It differentiates from siblings like dns_certificates and dns_lookup by emphasizing live TLS posture and grading.

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?

Usage is implied through the phrase 'Live TLS Posture' and the active handshake description, but there is no explicit guidance on when to use this tool versus alternatives such as dns_certificates or dns_profile. No when-not-to-use or alternative tools are mentioned.

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=false, so the read-only nature is covered. The description adds context that the data is "Public" (implying no authentication needed) and mentions "age in years", which is a derived value not visible in annotations. It does not contradict 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 a single, tight sentence that front-loads the core resource and then enumerates the exact data fields. Every word contributes, with no fluff or repetition of the name/title. It is an excellent model of 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?

Since there is no output schema, the description appropriately lists the key returned fields (registrar, creation date, expiration, name servers, age). It might omit some potential WHOIS fields (e.g., status, updated date), but the core information is communicated, and the tool is simple with one parameter and strong annotations. Adequate for use.

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

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

The schema provides 100% coverage of the single parameter with a clear example ("Domain name, e.g. example.com."). The description adds no additional parameter semantics beyond what the schema already includes, 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 clearly specifies the resource ("Public WHOIS profile") and the specific data fields returned (registrar, creation date, expiration, name servers, age in years), which distinguishes it from sibling DNS tools like dns_lookup or dns_certificates. Though there is no explicit verb, the implied action of retrieving a WHOIS profile is unambiguous given the tool name and 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?

The description implies the tool is for retrieving domain registration details by listing WHOIS-specific fields, but it does not explicitly state when to use this over alternatives such as dns_profile or dns_lookup. There are no when-not conditions or alternative names provided, so the agent must infer the use case from the data field list.

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 non-destructive behavior, so the description does not need to restate these. It adds some context by specifying 'curated' list, implying a maintained database, but does not describe response behavior (e.g., booleans, error handling) or edge cases. However, given the simplicity and annotation coverage, this is adequate.

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, focused sentence that front-loads the core action and resource. It contains no filler or redundant information, and every word contributes to understanding. This is concise and well-structured.

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 boolean check with one parameter and comprehensive annotations, the description is nearly complete. It clearly states the purpose and input, and the output (true/false) is implied by 'Test whether'. However, there is no output schema, so a brief mention of return value or behavior for invalid domains would make it fully complete. Given the simplicity, this is a minor 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?

The schema describes the 'domain' parameter with a concrete example ('mailinator.com'), so schema coverage is 100%. The description adds minimal extra meaning beyond the schema, just emphasizing the curated nature of the list. The baseline score of 3 is appropriate when the schema fully documents the parameter.

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 function with a specific verb ('Test') and resource ('whether a domain belongs to the curated disposable-email-domain list'). This distinguishes it from sibling tools like email_free_provider and email_validate, which have different purposes. The scope is 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 implies the use case (testing disposable email domains) but does not explicitly state when to use this tool versus alternatives like email_free_provider or email_validate. There is no mention of exclusions or prerequisites, so while the purpose is clear, guidance is limited.

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 description only needs to add context beyond that. It adds "curated," implying a maintained list that might not be exhaustive, which is useful. However, it does not disclose behavior such as how missing domains are handled or the reliability of the list. With annotations covering the safety profile, a 3 is appropriate.

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, front-loaded sentence that conveys the tool's purpose with no filler or redundancy. Every word contributes to 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?

The tool is simple (one parameter, no output schema) and the description gives a clear predicate-style purpose. However, it does not explicitly state the return type (e.g., boolean), which could be slightly ambiguous. The openWorldHint annotation covers some incompleteness, but for a tool with no output schema, a bit more detail on the result would make it fully complete. Overall, it's nearly complete.

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

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

Schema description coverage is 100% and the parameter description ("Domain to test, e.g. gmail.com.") fully explains the parameter. The main description does not add additional meaning beyond what the schema already provides, so the baseline score of 3 is justified.

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 ("Test") and resource ("domain") with a clear criterion ("curated free consumer-email-provider list"). It distinguishes this tool from siblings like email_disposable (checks disposable vs. free) and email_validate (checks format/SMTP).

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 this tool is for checking if a domain is a free consumer email provider, but it does not explicitly state when to use it over alternatives or provide exclusionary guidance. It lacks the "when not to use" or named alternatives seen in higher-scoring examples.

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 provides substantial behavioral detail beyond the annotations: it explains the live probe mechanism, the verdict categories, the catch-all detection method (random-fake-RCPT comparison), the automatic skip behavior for certain providers, and expected latency (3-8s). This enriches the safety hints already provided by annotations and fully discloses behavioral traits.

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 concise sentences, each packing important information: protocol, verdicts, catch-all method, provider skips, and latency. There is no redundancy or filler; the description is front-loaded and highly efficient.

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

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

Given the tool's complexity (live SMTP probe with multiple outcomes), the description is complete: it lists the protocol, all possible verdict values, the catch-all detection technique, provider limitations, and latency. Even without an output schema, the return values are enumerated, and the tool's behavior is fully characterized.

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 only 50% (email is described, check_catch_all is not). The description compensates by explaining catch-all detection via random-fake-RCPT comparison, which gives meaning to the check_catch_all parameter. While it does not explicitly describe the parameter's default or effect when false, the addition is useful and partially fills the gap.

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 function with a specific verb ('probe') and resource ('SMTP RCPT'), plus the exact protocol steps (HELO + MAIL FROM + RCPT TO; no DATA). It distinguishes itself from siblings like email_validate by focusing on live SMTP probing and deliverability verdicts, and explicitly lists the possible outcomes.

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 clear context on when this tool is appropriate (live SMTP probing) and includes an important constraint: it is automatically skipped for major providers (Gmail, Outlook, etc.). However, it does not explicitly name alternatives or state when to prefer other tools, so it lacks a direct when-not-to-use comparison.

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=false. The description adds behavioral constraints beyond annotations: 'Demo mode is allowed; no live SMTP probe' and the specific checks performed (MX lookup, typo correction). This enriches the agent's understanding of what the tool does and does not do.

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 sentence that front-loads the primary verb and resource, followed by a compact list of capabilities and constraints. Every word earns its place, with no redundant or filler content.

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

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

With no output schema, the description should clarify what the return value looks like. It mentions a 'composite deliverability score' and flags, but not the exact structure or how to interpret the typo correction output. For an agent needing to parse results, this is a minor gap, though the tool's input and checks are well covered.

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 schema covers the 'email' parameter but leaves 'check_dns' without description (50% coverage). The description mentions MX lookup, which relates to DNS checking, but never explicitly explains the 'check_dns' boolean toggle. For a 2-param tool, the lack of clarity on 'check_dns' is a gap, though the email parameter is self-evident.

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 'Validate' with a clear resource 'email address' and enumerates distinct checks (RFC syntax, MX lookup, disposable/free/role flags, typo correction, composite score). This clearly differentiates it from sibling tools like email_disposable or email_smtp_probe, which focus on only one aspect.

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 by listing included checks and explicitly states 'no live SMTP probe', which signals that email_smtp_probe should be used for that specific capability. It also notes 'Demo mode is allowed', giving context for test usage. However, it does not explicitly say 'use this when you need a complete validation' 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, and destructiveHint. The description adds valuable behavioral context beyond these: 'Returns every observation across every reported unit, most-recent first' clarifies the scope (all units) and ordering (most-recent first), which are not disclosed in the annotations. This helps the agent understand what to expect in the response.

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 purpose and use case, and every word earns its place. No redundant or filler content.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does state 'Returns every observation across every reported unit, most-recent first,' which covers the scope and ordering. However, it doesn't mention potential size limits or pagination, and the behavior of 'include_segments' is left unclear. Given the tool's complexity, this is slightly incomplete but still adequate.

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 only 33% (only 'concept' has a description). The description adds little for the other parameters: 'ticker' is self-evident but not described, and 'include_segments' is not explained. The phrase 'every reported unit' ambiguously hints at segment behavior, but it's not explicit. Since coverage is low, the description should compensate, but it does not.

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: 'Full observation history for one XBRL concept (any us-gaap tag).' It uses a specific verb ('Returns') and resource ('observation history for XBRL concept'), and distinguishes itself by noting it's for fields outside the 35-item headline catalog, setting it apart from sibling tools like equities_filings and equities_fundamentals.

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

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

The description provides clear when-to-use guidance: 'Use for fields outside our 35-item headline catalog.' This implies a specific condition for selection. It doesn't explicitly name an alternative for headline fields, but the context is sufficient for an agent to discern when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: 'live' indicates real-time data, 'most recent' indicates recency, and 'filter by form type' indicates a filtering capability. These are beyond what annotations alone 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?

The description is a single sentence with two clear clauses, front-loaded with the purpose ('Live SEC EDGAR submissions API'). It lists example form types and the key filter, with no redundant words or repetition of schema details.

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 retrieval tool with 4 parameters and no output schema, the description covers the core function, input identifiers, and filtering. It does not describe the return structure, but the concept of 'most recent filings' implies a list of filing records, which is adequate given annotations and simplicity.

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 75% (cik, forms, ticker have descriptions; limit has only a default). The description reinforces the ticker-or-CIK requirement and form-type filtering, but does not add new semantics for the 'limit' parameter. It aligns with the schema without going beyond it, so a middle score 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 provides live SEC EDGAR filings (10-K, 10-Q, 8-K) for a ticker or CIK, distinguishing it from sibling equities_* tools by focusing on recent filings. It names the resource (SEC submissions), the action (retrieve most recent filings), and the scope (by ticker or CIK with form-type filtering).

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

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

The description gives clear context: when you need recent SEC filings for a company, using a ticker or CIK, with optional form-type filtering. It does not explicitly name alternatives (e.g., 'use equities_fundamentals for financial ratios'), but the context is unambiguous for this specific filings use case.

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 safe read-only nature is covered. The description adds useful behavioral context by noting it is 'Free — backed by SEC's public XBRL companyfacts API' and that the data is 'parsed' and 'curated,' implying a structured/simplified view rather than raw filings. This goes beyond the annotations without contradicting 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 two sentences and efficiently packs core information: what the tool returns, the specific metrics, the period options, and the free/public data source. Every clause adds value, and it is front-loaded with the most important content. No fluff or 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 simple parameter set and strong annotations, the description covers the essential context: the data source (SEC XBRL), the content focus (headline statements), and the period granularity. The lack of an output schema is partially mitigated by listing the metrics returned. It does not describe return structure or pagination, but for a tool of this simplicity with read-only/idempotent hints, 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 description coverage is low (33%; only ticker has a description). The description adds semantic meaning for the 'period' parameter by mapping annual to 10-K and quarterly to 10-Q, which is helpful. However, it does not explain the 'limit' parameter (though the schema provides min/max/default) and does not elaborate on ticker format or accepted values, so compensation for the low schema coverage is only partial.

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

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

The description clearly states the tool provides headline financial statements from SEC XBRL filings, explicitly listing key metrics like revenue, net income, total assets, EPS, and cash flow. It also differentiates from siblings by emphasizing 'curated tags' and the 10-K/10-Q annual and quarterly forms, which distinguishes it from equities_concept, equities_filings, and equities_ticker.

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—when you need headline fundamentals from SEC filings—by naming the specific metrics and the 10-K/10-Q basis. However, it does not explicitly state when to use this tool versus alternatives like equities_concept for raw XBRL concepts or equities_filings for filing metadata, so it stops at implied guidance rather than providing exclusions or named 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 and destructiveHint=false, so the safe read-only nature is covered. The description adds the source (SEC EDGAR registry) and specifies the returned fields, but does not disclose any edge-case behavior such as handling of unknown tickers or rate limits. This adds some value but not 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 a single, clear sentence that front-loads the verb and resource. It contains no filler and every word adds 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?

The tool is a simple lookup with one parameter and no output schema. The description adequately lists the output fields (company name, CIK, exchange, SIC, headquarters) and the data source. It does not mention error handling or limitations like ticker validity, but for this simple resolver the description is reasonably 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?

The schema description coverage is 100%, with the single 'ticker' parameter already documented as 'Stock ticker, e.g. AAPL.' The description does not add any extra semantics about the parameter beyond what the schema provides, so it meets the baseline but no more.

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 the specific verb 'Resolve' and clearly identifies the resource (stock ticker) and the output fields (company name, CIK, exchange, SIC industry code, headquarters). This distinguishes it from sibling tools like company_ticker (reverse mapping) and equities_filings.

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

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

The description implies when to use it—when you have a ticker and need company profile data from SEC EDGAR—but it does not explicitly mention alternatives or exclusions. There is no guidance on when to prefer this over company_ticker or company_cik, so usage guidelines are implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Summarize' aligns with a safe read operation. However, it does not clarify what 'loaded' means or what output format to expect, so behavioral transparency beyond annotations is minimal.

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, front-loaded sentence that is concise and free of unnecessary words. Every word contributes to the core 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?

For a simple one-parameter tool, the description gives a basic understanding of the purpose, but because there is no output schema, it does not hint at what the summary contains or how results are structured. This leaves a moderate gap for an 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?

The schema provides full coverage for the sole parameter 'airline_code' with a clear example. The description simply repeats 'carrier code' without adding any new semantic detail, so the baseline 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 uses the specific verb 'Summarize' and identifies the resource as 'loaded route reliability signals' for a carrier code, which clearly distinguishes it from sibling tools like flight_reliability or flight_route_summary.

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?

No guidance is given on when to prefer this tool over alternatives, such as flight_cancellation_risk or flight_reliability. No contextual hints or exclusions are provided.

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, covering the safety profile. The description adds 'across loaded route aggregates' as a scoping detail, but it is unclear what 'loaded' means, and no further behavioral traits (e.g., output format, aggregation method) are disclosed. With annotations, a score of 3 is appropriate.

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 sentence and appropriately sized, but it contains a repeated word ('loaded loaded') and an awkward construction that reduces clarity. It conveys the essential idea but is not polished, so it earns an average 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 (one parameter, no output schema) and helpful annotations, the description is adequate but not complete. It fails to clarify what 'delay and reliability signals' specifically entail or what 'loaded route aggregates' means, leaving some ambiguity. The presence of sibling tools provides context, but the description itself is minimal.

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% (airport_code with example 'ATL'), so the schema already fully explains the parameter. The description does not add additional parameter semantics beyond what the schema provides, matching the baseline for high 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 the specific verb 'Summarize' and identifies the resource as 'delay and reliability signals for an airport', which is distinct from sibling tools like flight_route_summary (route-level) and flight_airline_reliability (airline-level). The phrase 'loaded loaded route aggregates' is awkward and typo'd, but the core purpose is clear enough.

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 no explicit guidance on when to use this tool versus alternatives. It only implies the scope ('for an airport') but does not mention sibling tools such as flight_route_summary or flight_cancellation_risk, nor does it state exclusions or conditions. This is essentially no guidance beyond the basic purpose.

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 non-destructive hints. The description adds the useful context that data is historical and not live, but does not disclose output format, computation method, or rate limits. With annotations covering safety, the additional context is moderate.

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 concise sentences, front-loaded with the action and resource. There is no fluff or redundant 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?

For a simple read-only tool with no output schema, the description gives a basic idea of the return type ('signals') but does not explain what the signals actually look like or how they are structured. It also lacks sibling differentiation, but annotations and schema compensate for some gaps.

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

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

Schema description coverage is 100%, so parameters origin, dest, and month are already well documented. The description adds no extra parameter detail (e.g., month optionality or format), so it does not go 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 historical cancellation-risk signals for a route, using a specific verb and resource. It distinguishes from live tracking but does not explicitly differentiate from sibling flight tools like flight_reliability or flight_route_summary.

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 phrase 'This is not live tracking' provides clear context that the tool is for historical analysis, implying it should not be used for real-time status. However, it does not mention alternative tools or provide explicit when-to-use/when-not-to-use 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about demo mode restricting to selected loaded routes, which is a behavioral constraint not captured in annotations. However, it does not disclose what 'reliability' means (e.g., on-time percentage, cancellation rate) or describe the return format, which is a gap given there is no output schema.

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 concise sentence that states the core purpose and then lists relevant route examples. While the list of six route pairs is somewhat long, each example reinforces the input format. The structure is front-loaded with the verb and resource, and there is no filler or redundant 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?

The tool has no output schema, so the description should explain return values, but it does not. It also lacks differentiation from sibling flight tools (e.g., flight_route_summary, flight_cancellation_risk), which weakens completeness. The demo mode restriction is mentioned but not elaborated (e.g., what happens for non-demo routes). Given the simplicity of the tool and the presence of annotations, the description is incomplete for full contextual understanding.

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% description coverage for all three parameters (origin, dest, month), so the baseline is 3. The description adds route examples that map to origin/dest, but it does not explain the optional month parameter or add any semantic nuance beyond the schema. The parameter semantics are adequately handled by 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 'Return historical route reliability', which is a specific verb+resource. It provides concrete route examples (ATL-LGA, ORD-EWR) that illustrate the input format. While it doesn't explicitly distinguish from sibling tools like flight_route_summary or flight_cancellation_risk, the focus on 'historical reliability' is a distinct 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 implies usage for checking historical reliability on specific routes, with the demo mode examples providing some context. However, there is no explicit guidance on when to use this tool versus alternatives like flight_route_best_times or flight_airline_reliability. The lack of exclusions or alternative tool references leaves the usage guidelines implied rather than explicit.

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 covered. The description adds context about the ranking logic (by historical reliability score) but does not disclose details like what 'loaded' means, how many buckets are returned, or how the ranking is ordered beyond reliability. This is acceptable given the annotations, but not exceptionally informative.

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 sentence that directly states the tool's function. No redundant words or filler. It is appropriately sized for a simple tool with one parameter.

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 low complexity (one parameter, no output schema) and strong annotations, the description sufficiently conveys the tool's core behavior. However, it omits any explanation of the output format or the meaning of 'reliability score', which could leave some ambiguity. Still, it is complete enough for a straightforward ranked-list 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% for the single 'route' parameter, with a clear format example. The description does not add further parameter details, but the schema already provides sufficient meaning, so the baseline of 3 applies.

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 a specific action ('Rank') with a clear resource ('loaded departure-hour buckets for a route') and a criterion ('historical reliability score'). This distinguishes it from sibling tools like flight_reliability (which focuses on overall reliability) and flight_route_summary (which provides route summaries).

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?

No explicit guidance is given on when to use this tool versus alternatives. The description implies use for a route, but does not mention related tools like flight_reliability or flight_airport_delay_profile, nor does it clarify edge cases such as how to interpret 'loaded' buckets.

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, idempotent, and open-world hints. The description adds useful behavioral context by clarifying the response is historical (not live) and enumerating the dimensions included, which sets expectations for the output. 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 two sentences with no fluff. The first sentence states the purpose and output contents; the second removes ambiguity about live tracking. Every word serves a 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?

For a simple two-parameter read-only tool with no output schema, the description adequately covers the tool's purpose, scope, and expected output components. It could add more caveats but is sufficiently complete 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 coverage is 100% and both parameters are clearly described as airport codes (e.g., ATL, LGA). The description adds no additional parameter semantics beyond what the schema already provides, 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 uses a specific verb ('Return') and a specific resource ('combined historical route summary') with detailed contents (reliability, cancellation risk, carriers, months, best time bucket). It distinguishes from sibling tools by emphasizing 'combined', showing it aggregates data covered by more specialized siblings.

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 an exclusion ('This is not live tracking') but does not explicitly say when to use this tool over alternatives or name the specialized siblings. The 'combined' wording implies it is for an overall summary, but guidance is more implied than explicit.

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 establish the tool as read-only, idempotent, and non-destructive. The description adds valuable context about the content (fields like FRED ID, title, units, frequency) and its relationship to fred_series, going beyond what annotations state. It does not contradict 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 compact, consisting of two sentences that front-load the primary purpose and then provide a clear usage directive. Every word earns its place without redundancy or filler.

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?

This is a simple, parameterless tool. The description sufficiently conveys what the tool returns (a list with specific fields) and how to use it in relation to fred_series. No output schema exists, but the description covers the essential information an agent would need.

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 tool has zero parameters, and the description accurately notes the catalog's purpose. Since there are no parameters to explain, the baseline of 4 applies; no additional parameter information is needed.

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 function: listing curated FRED series shortcuts with their FRED ID, title, units, and frequency. It also differentiates itself from sibling tools like fred_series by explicitly noting it serves as a catalog for discovering available slugs.

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

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

The description provides clear usage context by recommending the catalog for discovering slugs available for fred_series. While it does not explicitly mention when not to use it or name alternative tools, the intended use case is evident and distinct from 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: results are 'ordered by popularity' and the catalog size (800k series), which are not captured by annotations.

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

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

Two concise sentences with no filler. The purpose, usage guidance, and an example are all packed efficiently while remaining easy to read.

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

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

The description covers purpose, when to use, and result ordering. It lacks explicit return format details, but the example implies the output (series IDs and variants). For a simple search tool with good annotations, this is fairly complete, though it could mention pagination or limit behavior.

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 0%, so description must compensate. It explains the meaning of 'q' through 'free-text search' and an example, but does not mention 'limit' at all. The schema provides defaults and bounds, so limit is self-explanatory, but description adds minimal value for it.

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 is for free-text search of FRED's ~800k series catalog. It explicitly differentiates from siblings by saying 'Use when you don't know the series ID', which contrasts with likely fred_series requiring an ID.

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 when-to-use guidance: 'Use when you don't know the series ID'. Also gives a concrete example with 'initial jobless claims' and notes it surfaces ICSA and variants, indicating expected use cases.

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, non-destructive. The description adds scale (~800k series), data sources (BLS, Census, Fed, etc.), and the requirement of a server-side key. This is meaningful context beyond annotations, though it doesn't cover return format or pagination behavior.

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, front-loaded with the core action. The example lists are helpful but not bloated; the second sentence packs source coverage and key requirement efficiently.

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 5-param tool with no output schema, the description covers the essential usage, scope, and authentication. It lacks return format/pagination details, but the context signals and sibling names clarify it's a data-fetch endpoint.

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 schema covers 60% of parameters, including descriptions for series_or_slug and start/end. The description reinforces series_or_slug with concrete examples (gdp, CPIAUCSL) and clarifies the dual-mode input. It doesn't add much for sort/limit, but those are already constrained by schema defaults and enums.

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?

Clearly states the action ('Fetch any FRED time-series') and the identifier method (curated slug or raw FRED ID). This distinguishes it from siblings like fred_search (which searches for series) and fred_popular (which lists popular series).

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 context: use when you have a specific curated slug or raw FRED ID and want the time-series data. Doesn't explicitly reference alternatives like fred_search or fred_popular, so it lacks an explicit when-not, but the naming and description imply the intended use.

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, idempotent, and open-world behavior. The description adds value by explaining that data is fetched 'live from EDGAR', that the score is 'recency-weighted', and that the action hint is tuned by buyer profile. It does not contradict annotations and provides useful 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?

The description is two well-structured sentences, front-loaded with the core purpose and then elaborating on outputs. There is no fluff, and every sentence contributes to understanding the tool.

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 no output schema, the description should explain the return shape more thoroughly. It mentions the three output components (score, cadence hint, action hint) but leaves out details about how limit and window_days influence results and what 'envelope' means. It is adequate but has clear gaps.

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

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

Schema description coverage is only 40%, so the description should compensate for the undocumented parameters. While it explains the purpose of buyer_profile, it completely ignores limit, window_days, domain, and ticker, leaving the agent without guidance on how these parameters affect results. The description adds minimal value beyond the schema.

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

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

The description clearly states the tool's function with specific verbs ('Pulls', 'surfaces') and a precise resource ('SEC Form D / D-A filings from EDGAR'). It also distinguishes itself from generic funding tools by detailing the output components (score, cadence hint, action hint) and the buyer-profile tuning, which is unique among siblings.

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

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

The description provides clear context that this tool is for accessing authoritative funding signals from SEC Form D filings, implying when it should be used. However, it does not explicitly state when not to use it or mention any alternative tools, so it falls short of a 5.

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 description does not need to repeat these. It adds the useful nuance that the conversion uses the 'most recent reference rate' rather than a live trading rate, but it does not disclose output format or edge cases. This is comparable to a baseline 3 given the annotation coverage.

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, concise sentence that front-loads the core action. Every word contributes, with no redundant or filler content.

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

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

For a simple conversion tool with three required parameters and strong annotations, the description is largely sufficient. It specifies the rate type ('most recent reference rate'), which is an important behavioral context. However, it does not mention the return value (e.g., converted amount and/or rate), and given the large set of sibling FX tools, a brief differentiation note would enhance completeness. Still, it is adequate for most use cases.

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 67%, with both currency parameters having descriptive examples. The description adds that 'amount' is the value to convert and 'two currencies' implies from/to, but it does not clarify whether the amount is in the source currency, the expected precision, or the currency code format beyond what the schema already provides. It adds some meaning but does not fully compensate for the uncovered amount parameter.

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 an amount between two currencies using the most recent reference rate. It uses a specific verb ('convert') and resource ('amount between two currencies'), and the mention of 'most recent reference rate' distinguishes it from sibling tools like fx_historical or fx_rates.

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 usage context is implied: it is for converting an amount, not for simply looking up rates. However, there is no explicit guidance on when to prefer this over alternative FX tools like fx_rates or fx_pair, nor any exclusions or preconditions.

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 establish read-only and idempotent behavior. The description adds useful context by specifying the calculation methodology (Pearson, daily log-returns) and the banded output categories, which goes beyond the annotations. No contradiction exists.

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 with no redundancy. The first sentence states the core function, and the second adds output banding and use-case context. Every word earns its place.

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

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

The tool is simple with two optional parameters, and the schema provides names, types, defaults, and enums. The description explains the calculation and output format, which is sufficient for invocation. However, the gap in parameter semantics prevents a perfect score.

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 schema has 0% description coverage, and the description does not compensate. It mentions 'basket' but does not explain the 'basket' parameter values (g10, majors) or the 'horizon_days' parameter at all, leaving the agent without meaningful parameter guidance beyond the bare 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 it computes Pearson correlation of daily log-returns vs USD across a basket, which is a specific verb and resource. It distinguishes itself from sibling FX tools by focusing on correlation matrices and explicitly mentions output banding categories, differentiating it from tools like fx_timeseries or fx_pair.

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 a clear usage context: 'Treasury/risk workflow for understanding multi-currency exposure.' This tells the agent when to use the tool, but it doesn't explicitly exclude alternatives or name sibling tools, so it stops short of a perfect 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable context about the return content: complete list of currencies with central bank and peg classification. This goes beyond what annotations provide, though it doesn't discuss pagination or ordering, which are less critical for a small reference list.

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 sentence. It is concise, front-loaded with the action, and includes all necessary details without 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?

For a zero-parameter list tool with strong annotations, the description fully specifies what the tool returns and the scope of coverage. No output schema exists, but the description adequately covers that gap. It is complete for its simplicity.

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 tool has zero parameters, so the baseline is 4. There is no parameter information to add; the description appropriately focuses on the output.

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

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

The description clearly states the tool lists all currencies with reference-rate coverage, including central bank and peg classification. The verb 'List' and specific resource scope strongly distinguish it from sibling FX tools that provide rates, conversions, or historical 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 implies the use case: when the agent needs the universe of supported currencies and their metadata. It does not explicitly name alternatives like fx_rates or fx_convert, but the context is clear enough that an agent would know this is the go-to for currency listing.

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, non-destructive, and openWorld hints. The description adds only the 'reference rate' and 'specific past date' context, which is useful but thin; it does not address edge cases like weekend dates or data availability.

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