Ready APIs

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

Annotations already communicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the actual output payload — full ZIP enrichment including demographics, risk, climate, nearby airport, and hazards. It does not describe behavior on invalid addresses, but given the strong annotation coverage, this is a minor gap.

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 with no filler. It front-loads the action and resource, then packs the key enrichment categories into a parenthetical list. 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?

For a tool with a single required parameter, strong annotations, and no nested schemas, the description is complete enough for selection and invocation. It states the input type, the US scope, and the main output categories. The absence of an output schema is partially mitigated by the explicit enrichment list, though exact response structure is not described.

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 schema already states 'Free-form US address: street, city, state, ZIP.' The description only repeats the 'US address' concept and adds no new parameter semantics beyond the schema. A baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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') and resource ('US address'), then clearly lists the enrichment output: demographics, risk, climate, nearest airport, hazards. This distinguishes address_enrich from sibling tools like address_validate and geo_zip_lookup without needing to open schemas.

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 'in one call' phrase and the enumerated enrichment categories give an agent clear context for when this tool is appropriate. It does not explicitly name alternatives or exclusion criteria, such as using address_validate when only validation is needed, but the use case is clearly understandable.

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, non-destructive behavior. The description adds useful behavioral detail beyond annotations: it standardizes street/unit/city/state/ZIP and cross-checks ZIP against the geo dataset for state and city consistency. No contradiction exists, though it does not cover error handling or output shape.

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 purpose and then adds necessary specifics. There is no redundant text or filler; every clause earns its place.

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

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

For a one-parameter read-only tool, the description sufficiently defines the input form and the underlying validation/standardization process. The absence of an output schema is slightly mitigated by the description's mention of standardized components and ZIP consistency, but it never explicitly states the return value or invalid-address 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?

The schema already documents the address parameter with 100% coverage, so the baseline is 3. The description reinforces that the address is free-form and lists components, but it adds no syntax examples, format expectations, or canonicalization rules 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 names a specific resource (US address) and specific operations: parse, validate, standardize, and cross-check ZIP consistency. It is clear about what the tool does, but it does not explicitly differentiate from siblings like address_validate_batch or address_enrich, so it stops short of a perfect score.

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

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

The description makes clear this tool is for a single free-form US address needing normalization and validation, which implies appropriate use. It does not explicitly state when to prefer address_enrich or address_validate_batch, so exclusion guidance is missing.

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 operation is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those hints by disclosing that per-item errors are returned inline, which tells the agent that one invalid address will not necessarily fail the entire batch.

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 first sentence leads with the action and scope, and the second adds the key error-handling behavior. Every phrase 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?

For a simple single-parameter tool with rich annotations and full schema coverage, the description is largely sufficient. It covers scope, batch limit, and inline error behavior. A minor gap is the lack of any statement about the success response shape, though no output schema exists to compensate for that.

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

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

Schema description coverage is 100%, so the schema already documents the items parameter well. The description largely restates this ('up to 50 US addresses') rather than adding new parameter-level meaning, 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 states a specific verb ('Validate'), a clear resource ('US addresses'), and a concrete scope ('up to 50... in one request'). This clearly distinguishes it from the single-item sibling address_validate and from enrichment-oriented siblings like address_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 provides clear context: use this when validating multiple US addresses in a single call. It does not explicitly name alternatives or state when-not-to-use, but the batch scope and limit make the intended use obvious.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses meaningful behavior: Luhn-checking, that full PANs are never echoed, PCI-safety, and the exact fields returned. This gives an agent a concrete safety and data-handling picture without needing to inspect external documentation.

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

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

Three dense, front-loaded sentences with no wasted words. The first sentence establishes purpose and outputs, the second covers input validation and safety, and the third summarizes the return contract. Every sentence earns its place.

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

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

With no output schema, the description compensates by explicitly listing return fields: scheme, card_type, brand, issuer_bank, country, and risk_band. It also covers input formats, validation, and PCI-safety. Combined with the schema and readOnly annotations, this is complete enough for an agent 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 100%, so the baseline is 3. The description adds value by clarifying that input is validated via Luhn and that the PAN is never echoed, going beyond the schema's format description. The use_binlist_fallback parameter is already well-described in the schema, so no additional compensation is needed there.

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 ('Identify') and resource ('card BIN'), listing the exact data points returned: issuing bank, scheme, card type, and country. It is clearly distinct from any sibling tool, as nothing else in the sibling list covers BIN/card lookup. The input and output scope are 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 makes the use case clear: use this when you need to identify card/BIN issuer, scheme, type, country, and risk band. It does not explicitly name alternatives or state when not to use it, but the context is strong enough that an agent can infer the appropriate invocation.

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, so the safety profile is covered. The description states the additive behavior and that it returns a business day, but it does not disclose the definition of 'business day' (e.g., weekends and US holidays), how non-business-day start dates are treated, or whether negative day counts are supported. No contradiction with annotations 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 a single direct sentence with no filler, and the core operation is front-loaded. It is appropriately concise, though slightly too terse to include the US-holiday context and output format 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 two-parameter tool, the description is close to sufficient: the schema covers the date format and the description covers the operation. But with no output schema, it does not state the output date format, and it leaves the exact business-day calendar ambiguous, so an agent must make reasonable assumptions.

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 already documents the date format, and the description maps the days parameter to 'N business days', giving it basic semantic meaning. However, it does not specify constraints such as negative values, zero, maximum size, or how a non-business-day start date is handled, so the description only partially compensates for the schema's 50% coverage.

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

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

The description uses a specific verb and resource: 'Add N business days to a date' and states the return value, making the core operation clear. It does not explicitly distinguish itself from siblings like calendar_is_business_day or calendar_holidays, but 'add' is unambiguous enough that an agent can identify when it applies.

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 over related siblings such as calendar_is_business_day or calendar_holidays. It also does not mention use cases, prerequisites, or exclusions, leaving the agent to infer when this is the right tool.

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 meaningful behavioral context by specifying that dates are observed per OPM rules, which is a non-obvious detail since holidays can shift to weekdays. This goes beyond what the 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, front-loaded sentence with no filler. Every part contributes: the verb, the resource, the time scope, and the OPM observation rule.

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 one optional parameter, the description conveys the essential output: a list of holidays with observed dates. There is no output schema, so a bit more detail about return fields or date formatting could help, but the description is adequate for the tool's 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 schema has zero description coverage for the year parameter, so the description must carry the semantic load. 'For a year' only weakly signals the year parameter and adds little beyond the parameter's name. It does not explain accepted ranges, how OPM observation affects the parameter's meaning, or any other interpretation.

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 'List' is explicit and the resource 'US federal holidays' is precisely scoped. Adding 'including observed dates per OPM rules' clarifies the exact content and distinguishes this holiday tool from business-day siblings 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 use case is implied by the resource name, but the description never states when to choose this over the business-day sibling tools or when not to use it. There are no exclusions or conditional routing notes, so the agent has to infer usage from context.

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 no further action is expected. The description adds behavioral context beyond the schema by specifying the US scope and the internal rule (weekday and not a federal holiday), which clarifies exactly what is being evaluated. 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?

One clear sentence with no filler. The verb and resource are front-loaded, and the parenthetical definition efficiently explains the logic. 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?

For a one-parameter, read-only predicate tool, this description is essentially complete. The return value is implied as boolean by 'Check whether.' The US qualifier handles geographic scope, and the holiday definition is explicit. The only minor gap is not stating the response format outright, but it is not necessary for such a simple 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?

The schema fully documents the single parameter as an ISO date (100% schema coverage), so the baseline applies. The description does not add parameter-format details, but it does add meaning to the date by framing it as a 'US date' in the context of the business-day check. This adds modest value but is not essential.

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 ('Check whether'), a clear resource ('a US date'), and the exact predicate ('business day (weekday and not a federal holiday)'). This fully distinguishes it from sibling tools like calendar_business_days_add or calendar_holidays without requiring schema inspection.

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 makes the tool's use case obvious: call when you need to know if a given date is a US business day. However, it does not explicitly mention when not to use it or point to alternatives (e.g., calendar_business_days_add for adding business days, calendar_holidays for holiday lists). Usage is implied, not contrasted.

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 a safe read-only, idempotent operation, and the description adds substantive behavior: it pulls live EDGAR data, classifies 8-K item codes into seven categories, and computes a score and action hint. This goes beyond the structural hints without contradicting them. It stops short of explaining failure modes or data freshness, but the live-source caveat is helpful.

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 two-sentence description is compact and front-loaded with the SEC/EDGAR anchor before listing outputs. Minor redundancy, such as '8-K' and 'public company' appearing twice, keeps it from being perfect, but every sentence earns its place.

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

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

For a tool with no output schema, the description does communicate the key return elements: score range, dominant theme, and buyer-tuned action hint. It also names the filing source and change categories. Gaps remain for limit/window_days semantics and the exact output shape, so the description is useful 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 description coverage is only 40%, so the description needed to compensate. It does clarify buyer_profile by listing its values and tying it to the action_hint output, and domain/ticker are already described in the schema. However, limit and window_days remain wholly unexplained beyond their raw min/max/default constraints.

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

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

The description names a specific resource (SEC 8-K filings from EDGAR) and a precise processing pipeline: classify item codes into change categories and return a change-velocity score, theme, and action hint. This makes the tool's purpose unmistakable. However, it never explicitly distinguishes itself from near-siblings like company_changes or company_signal, so it falls short of a 5.

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 use cases through 'buyer-shaped action_hint tuned by buyer profile' with enumerated profiles like sales_outreach and recruiter, which tells an agent roughly when this tool is valuable. But it provides no explicit when-to-use/when-not-to-use guidance and does not name alternative tools or exclusion conditions.

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 structurally covered. The description adds genuinely useful behavioral context ('time-ordered' ordering, monitoring-oriented change types) that goes beyond the schema, but it does not disclose pagination behavior, response volume implications, or that an unfiltered call returns a default 7-day window. No contradiction with annotations.

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

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

Three tight, front-loaded sentences with zero waste: sentence one frames the domain, sentence two states mechanics (output and filters), sentence three gives the why. Every clause earns its place and the most decision-relevant information appears first.

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, idempotent monitoring tool with rich annotations, this is nearly complete: the agent knows what is returned, how results are ordered, the main filters, and the intended use case. Minor gaps remain — no guidance on valid change_type values (no enums exist in the schema) and pagination semantics are left to the schema, but the default values there partially mitigate this.

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% — between the low and high thresholds — so the schema does much of the documenting work. The description echoes the semantically central filters (since-date, LEI, change_type, country) and ties them to the monitoring purpose, adding light value. However, page and per_page have no schema descriptions and the description does not compensate for them, so those parameters remain under-explained.

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 names a specific resource (vendor/counterparty entity changes) with a concrete output ('time-ordered entity changes' with examples like status flips, parent acquisitions, renames) and explicit filter axes. It is clear and specific, but it does not explicitly differentiate this plural company_changes tool from the sibling company_change (singular) or company_timeline, which an agent would have to disambiguate by opening their schemas.

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 context is implied through 'Vendor / counterparty change monitoring' and 'Critical for continuous KYC and M&A monitoring,' which signals the monitoring scenario where this tool fits. However, there is no explicit when-to-use statement, no exclusion guidance, and no mention of the likely-overlapping sibling tools (company_change, company_timeline, company_signal), so the agent must infer when this is the right choice.

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 read-only, non-destructive, idempotent nature of the tool. The description adds useful behavioral context by explaining that CIKs are accepted with or without leading zeros and that the result is a normalized 'unified company profile'. This goes beyond the schema and 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, front-loaded sentence followed by a compact illustrative example. Every element earns its place, and there is no redundant filler. It is highly scannable for an agent.

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 one-parameter lookup with safety annotations and no output schema, the description is complete. It explains what input is accepted, how the input may be formatted, and what kind of result is returned. No additional details are necessary for a correct tool selection or invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description and schema both give the '320193' / '0000320193' examples, adding only the Apple mapping. The parameter's meaning is clear, but the description does not substantially enrich the schema's own documentation.

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 ('SEC EDGAR Central Index Key') with a precise output ('unified company profile'). The example '320193 = 0000320193 = Apple' makes the tool's purpose unmistakable. It also differentiates from sibling company identifier tools by focusing specifically on SEC CIK rather than ticker, domain, or EIN.

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 the use case: when you have an SEC CIK and want a company profile. It notes that CIK formatting is flexible, which removes a common usage question. It does not explicitly mention alternatives like company_ticker or company_domain, so it lacks the 'when-not-to-use' guidance needed 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?

The annotations already signal that this is read-only, idempotent, and non-destructive, so the behavioral burden on the description is lower. The description adds one useful fact: classification relies on a 'loaded curated company profile set,' implying offline/predefined data rather than live enrichment. It does not disclose behavior for unknown domains, output structure, or fallback semantics, but the annotations carry much of the safety profile.

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 starts with the action verb and object. There is no redundant filler, though the phrase 'loaded curated company profile set' is somewhat vague. It is concise without being overly skeletal.

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 one-parameter tool, the schema covers the input and the annotations cover safety, so the description does not need to be long. However, with no output schema, the description's failure to define what 'classify' returns leaves the agent uncertain about the result format or categories. The absence of any pointer to sibling tools also weakens 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 already fully documents the single 'url' parameter with an example ('nvidia.com'), so schema coverage is 100%. The description's 'domain' wording simply reinforces the schema rather than adding new normalization, formatting, or validation semantics. A baseline of 3 is appropriate because the description adds no meaningful parameter-level detail 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 states a clear verb and object ('Classify a domain'), making it easy to identify as a classification tool. However, it does not specify what classification result is returned or how it differs from sibling tools like company_industry or company_enrich. It is clear but not fully specific.

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 company_classify versus alternatives such as company_search, company_industry, company_signal, or company_enrich. The phrase 'using the loaded curated company profile set' hints at a conditional data source but does not state when this tool should be preferred. The agent is left to infer usage context.

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 readOnlyHint, idempotentHint, and destructiveHint, so the description is not required to restate safety. It adds the behavioral note that 'Demo mode allows selected sample domains,' which hints at restricted availability but is vague about what demo mode entails, who it applies to, or when it activates. This is minor added context beyond annotations but lacks clarity.

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 with the core action front-loaded. The 'Demo mode' clause adds a behavioral footnote but is not verbose or redundant. It earns its place by informing about a limitation, though it could be worded more transparently.

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 one-parameter, read-only lookup tool with rich annotations, the description is nearly sufficient but leaves gaps. The term 'Demo mode' is unexplained, and the output shape of a 'company profile' is not described, which could matter given there is no output schema. The domain input format is covered by the schema, but the overall tool behavior is only partially contextualized.

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 the parameter 'domain' described as 'Company domain or URL.' The description echoes this by using 'by domain' and 'sample domains' but does not add format examples, normalization rules, or edge-case handling. Baseline 3 is appropriate because the schema already documents the parameter sufficiently.

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 and resource ('Return a company profile by domain'), making the tool's primary function clear. It does not explicitly distinguish itself from siblings like company_enrich or company_lookup_auto, but the domain-based lookup is evident from the name and phrasing. The mention of 'Demo mode' introduces a slightly ambiguous secondary detail but does not obscure the core 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?

No guidance is given about when to use this tool versus alternatives such as company_enrich, company_lookup_auto, or company_search. The phrase 'by domain' implies the input type, but there is no explicit context for selecting this tool over siblings, nor any exclusion or preference statement. The 'Demo mode' reference is not actionable usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat safety. It does add context with 'bounded request' and 'demo mode allows selected sample domains', which provides a useful constraint, though demo mode remains vague.

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

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

The description is concise and front-loaded with the core action and scope. The demo-mode sentence adds useful context, though it is somewhat imprecise and could arguably be refined without harming 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?

For a single-parameter read-only batch tool with strong annotations and 100% schema coverage, the description is almost complete. It lacks detail on what a returned 'company profile' contains and on demo-mode sample selection, but the low complexity makes this 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?

Schema description coverage is 100%, with the domains parameter clearly documented including min/max items, example values, and comma-separated string acceptance. The description adds no parameter details, but the baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states it returns multiple company profiles by domain in one bounded request, conveying both the verb and resource. It distinguishes itself from single-domain lookups through 'multiple' and from unbounded queries through 'bounded', though it does not name sibling tools explicitly.

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 'multiple company profiles by domain in one bounded request' phrasing implies batch usage when several domains are needed at once, which is a weak usage cue. However, it gives no explicit guidance about when not to use it or which alternative to choose (e.g., company_domain for a single lookup).

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, non-destructive behavior. The description adds useful context beyond that: it lists the data domains covered, flags SEC filings as conditional on public status, and positions the tool as an aggregate response rather than a single-field lookup.

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, dense sentence with no filler. The headline value proposition "One-call" is front-loaded, followed by a compact list of included data categories, and the conditional SEC note is efficiently embedded.

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 single required parameter, rich annotations, and no output schema, the description does enough by enumerating expected result categories and flagging the public-company condition for SEC filings. It could go further by explaining response format or handling of missing data, but these are minor for a one-parameter enrichment 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?

The input schema already documents the only parameter (domain) with an example, so description-level parameter guidance is not needed. The description adds no new parameter semantics, but the schema's 100% coverage justifies the baseline score.

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 names a specific resource (company domain) and lists concrete output categories: identity, DNS, tech stack, SEC filings, and cyber risk score. It clearly distinguishes this aggregated tool from specialized siblings like tech_stack, dns_lookup, and cyber_risk by emphasizing a single consolidated 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?

"One-call" implies use when a consolidated company enrichment snapshot is needed, and the component list clarifies scope. However, the description does not explicitly name alternatives, state when not to use this tool, or explain how it compares to company_insights or company_lookup_auto.

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 'loaded curated' and the ability to match on category or description signals, but it does not disclose match semantics, result limits, or whether the query is exact or fuzzy. With annotations present, this is adequate but not deeply 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?

A single sentence, front-loaded with the action and resource, and no filler. Every word contributes to understanding; the description is efficient for its scope.

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 one-parameter, read-only search tool, the description is mostly sufficient, but there is no output schema and no mention of what fields are returned or how results behave (e.g., fuzzy matching, pagination). It also leaves the choice between this and similar company search tools ambiguous.

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 already describes the sole parameter 'industry' with an example, and schema coverage is 100%. The description adds useful meaning by clarifying that the query applies across industry, category, or description signals, which the schema alone does not convey.

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 concrete operation ('Search') and a specific resource ('loaded curated company profiles'), and names the search dimensions (industry, category, description signals). This sufficiently conveys what the tool does, though it does not explicitly differentiate it from sibling tools like company_search or company_classify.

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 related siblings such as company_search, company_lookup_auto, or company_classify. The description implies a use case but leaves the selection logic entirely to inference, which is risky given the large sibling set.

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, open-world, non-destructive behavior, so the description only needs to add context beyond safety. It does add meaningful behavioral context by disclosing that this endpoint aggregates multiple distinct data sets into one response, which implies a larger combined payload than a single-purpose endpoint. It does not mention latency or output shape, but with annotations covering the safety profile this is a reasonable contribution.

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 short and front-loaded: the first line states the core value proposition and the included categories. Minor marketing phrasing like 'mega-endpoint' and the redundant 'everything we know' label add a little color without adding much information, but overall it is efficiently written.

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 complex 10-parameter aggregator with no output schema and dozens of narrower sibling tools. The description does not clarify which identifier parameter to provide, whether at least one is required, what the response structure looks like, or how this relates to focused tools like company_enrich. An agent can infer broad intent but not safely invoke it for a specific use case without more 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?

Schema coverage is only 10%, with just include_filings documented. The description does not explain how to choose between lei, domain, and ticker, whether any identifier is required, or how the include_* flags map to the listed data categories. For a heavily optional-flag endpoint with low schema coverage, the description supplies almost no parameter-level meaning.

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 this as a single-call aggregate company endpoint and enumerates the bundled data categories: profile, hierarchy, corporate-family network, lifecycle timeline, and peer benchmark. This distinguishes it from narrower company tools, though it relies on a label ('everything we know') rather than a precise verb and resource statement.

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 implies use when you want broad company intelligence in one call ('Single-call mega-endpoint', 'everything we know'), which is useful guidance. However, it never states when not to use it or names alternatives like company_enrich, company_network, company_timeline, or company_peer_comparison, leaving routing to inference despite many siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that the tool auto-detects and routes the identifier and returns resolution.matched_on for confirmation. This goes beyond the annotations and helps the caller verify which identifier type was actually 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?

Two focused sentences with no filler. The core routing behavior is front-loaded, followed by the accepted identifier types and the key return field. Every sentence adds value.

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

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

For a single-parameter, read-only, idempotent lookup tool with no output schema, the description covers the essential call context well: accepted inputs, auto-routing behavior, and the confirmation field. It could mention ambiguity handling or what the full resolution response contains, but given the low complexity and strong annotations, the definition is 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 identifier property already enumerates the accepted types with helpful detection hints. The description repeats the same list without adding new semantic detail about formatting, normalization, or conflict resolution. Baseline 3 is appropriate because the schema carries the parameter meaning.

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 behavior: auto-detect identifier type and route. It lists the accepted identifier types and explicitly distinguishes this tool from siblings like company_cik, company_domain, and company_ticker by its auto-detection behavior. It is clearly a generic entry point for identifier-based company lookup.

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

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

The description implies when to use this tool: when the identifier type is unknown or mixed. However, it does not explicitly say to prefer this over company_cik, company_domain, company_ticker, or company_lookup_batch when the type is already known. No alternatives or exclusion criteria are named, so usage guidance is 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?

The annotation set already covers read-only, idempotent, and non-destructive behavior. The description adds valuable behavior beyond that: the batch size ceiling, the mixed-identifier capability, the single POST transport, and the join-back property of results. No contradiction with annotations is present.

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

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

Two sentences carry all essential information with no filler. The limit, identifier types, HTTP method, and join-back property are all front-loaded and each sentence earns its place.

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

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

For a simple read-only batch lookup, the combination of schema and description is sufficient for correct invocation: the input shape is fully specified, safety is covered by annotations, and the join-back note clarifies a key output expectation. It could go further with examples or unresolved-identifier behavior, but nothing critical is missing.

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 already fully constrains the single parameter: an array of {type, value} objects with an enum and min/max items. The description reinforces that identifiers can be mixed and that original inputs are preserved for join-back, but it does not add per-type value format examples. Since there is only one well-schematized parameter, this is adequate.

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 ('Resolve') and clearly identifies the resource and action: batch lookup of company identifiers. It also names the accepted identifier types and the 50-item limit, which distinguishes it from single-identifier siblings like company_domain, company_ticker, and company_lookup_auto.

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 signals when to use this tool: when you need to resolve multiple mixed identifiers in one POST. It does not name alternatives or state exclusions, but the batch framing and identifier-type enumeration give an agent sufficient context to select it over single-lookup 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?

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses the traversal source (GLEIF), the aggregation behavior (every entity sharing the root), and a non-obvious default filter (pension/retirement trusts excluded). 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?

Two tightly written sentences that front-load the core behavior and then add a meaningful default-filter detail. No filler or redundant restatement of the title.

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 sufficiently explains what the tool returns and the default filter for a hierarchy-walking function, even without an output schema. Pagination behavior is left to the schema; additional detail about result item shape or no-root cases would be nice but is not essential.

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 60%, with lei/domain/per_page described. The description adds meaning to include_pension_trusts by noting the default exclusion, and reinforces the subject-resolution concept. Page remains undescribed in both schema and description, but the overall parameter intent is reasonably clear.

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 concrete action ('Walk the GLEIF ultimate-parent hierarchy') and result ('return every entity sharing the same conglomerate root'), naming both the resource and scope. This clearly distinguishes it from broad sibling tools like company_search or company_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 the full corporate family under a conglomerate root—and adds the default exclusion of pension/retirement trusts. However, it does not explicitly state when to prefer this over alternatives or when not to use it.

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 contradict them. It adds little beyond labeling the return as a 'nonprofit identity profile'; it does not describe not-found behavior, data coverage, or response shape.

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, front-loaded sentence with no filler or redundant restatement. Every word contributes to the tool's 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 single-parameter, read-only lookup with rich annotations, the description is reasonably complete. It covers the main input and the general nature of the result; the main gap is lack of guidance toward the sibling search tool when an EIN is unknown.

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 ein parameter already includes a type and example format. The description adds no additional parameter meaning beyond what the schema 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 states a specific verb ('Return'), a specific resource ('nonprofit identity profile'), and the lookup key ('by EIN'). This clearly distinguishes it from sibling tools such as company_nonprofit_search, which likely searches rather than looks up by EIN.

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 'by EIN' implies this tool is for use when the caller already has an EIN, but the description does not explicitly guide an agent to company_nonprofit_search when an EIN is unavailable. Usage context is present but largely left to inference.

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, covering the safety profile. The description adds the resource and search dimensions but does not disclose behavior like result limits, matching semantics, or whether multiple fields can be combined.

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 short sentence that front-loads the verb and resource, then enumerates the search keys. Every word earns its place and there is no redundant 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 two-parameter search tool with rich annotations, the description is largely complete. It identifies the resource and search dimensions, though it does not describe what profile fields will be returned, which could matter since there is no output schema.

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 adds value by clarifying that the q parameter can represent a name, category, EIN, or state, going beyond the schema's simple 'education' example and enriching the meaning of the query 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?

States a specific verb ('Search'), a specific resource ('nonprofit identity profiles'), and the four searchable dimensions (name, category, EIN, state). This distinguishes it clearly from siblings like company_search and company_nonprofit_ein without needing to open schemas.

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: an agent can infer to use this tool when searching nonprofit profiles by the listed keys. However, there is no explicit guidance on when to prefer this over sibling tools such as company_nonprofit_ein or company_search, nor any exclusions.

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 useful behavioral detail beyond annotations by specifying the exact nature of the comparison and the output dimensions, giving the agent a concrete picture of what the tool will produce.

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 is information-dense without padding. The main action is front-loaded, followed by concrete output specifics. Every phrase contributes to understanding.

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 states outputs and scope but leaves gaps: no output schema, no guidance on required identifiers, no mention that one of lei/domain/ticker is presumably needed, and no detail on how 'scope' alternatives behave. For a 4-parameter tool with zero required parameters, this is a notable completeness 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 covers 75% of parameters with descriptions for lei, domain, and ticker. The description does not add meaningful semantics about the 'scope' parameter beyond implying default same-industry/country behavior. It does not clarify how to choose among resolution identifiers or that at least one is expected, though schema provides basic resolution meaning.

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 verb, 'Benchmark', and a clear resource: a company against same-industry/same-country peers. It lists concrete output dimensions (employee distribution, jurisdiction mix, founding-decade histogram, rank) that distinctly separate this tool 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 clearly conveys the context for use: when a peer benchmark is needed, including what the comparison covers. It does not explicitly mention when not to use this tool or name alternative tools, but the context is unambiguous 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, and open-world behavior. The description adds the non-uniqueness caveat, which is a meaningful behavioral detail for interpreting results, and 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?

Two front-loaded sentences with no filler. The core purpose and the key caveat both earn their 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 simple 3-parameter lookup with full schema coverage and strong annotations, this is nearly complete. It lacks only a brief note on match behavior or returned profile shape, but nothing essential blocks correct invocation.

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

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

Schema description coverage is 100%, so the baseline applies. The description reinforces country's disambiguation role but adds little beyond the schema's own parameter descriptions and does not mention jurisdiction.

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

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

States a specific action ('Resolve a registry-assigned registration number ... to a company profile') with concrete registry examples. It is clearly distinct from other company_* tools by targeting registry-assigned identifiers, though it does not explicitly name a sibling alternative.

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

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

Provides explicit guidance to pass country= because registration numbers are not globally unique, which is important for disambiguation. It does not spell out when to choose this over company_lookup_auto or company_search, so it stops short of a full routing rule.

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 covered. The description adds the 'loaded curated' scope and the demo-mode limitation, which are useful but thin. No contradiction exists between the description 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?

Two sentences with no filler; the core search behavior and searchable fields are front-loaded, and the demo-mode note adds context without bloating the description.

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 one-parameter read-only search tool, the description covers the query semantics and the curated nature of the dataset. It lacks any mention of result limits, response shape, or how to use demo mode, but the absence of an output schema and the tool's simplicity keep the gap modest.

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 only describes q as a generic string with a 'technology' example, giving little semantic guidance. The description compensates by specifying that q may be a name, domain, industry, or ticker, meaningfully enriching the parameter's interpretation 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 identifies the operation ('Search') and the resource ('loaded curated company profiles'), and enumerates supported query dimensions: name, domain, industry, or ticker. It is clear on its face but does not differentiate from overlapping siblings like company_lookup_auto or company_ticker, so it stops short of a 5.

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 choose this tool over the many company_* siblings such as company_lookup_auto, company_domain, or company_ticker. The demo-mode remark is the only contextual hint, and it does not clarify use cases or exclusions. This leaves tool selection largely to inference.

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, covering the safety profile. The description adds context about data sources and the returned fields, but doesn't disclose any extra behavioral traits like rate limits or auth requirements, which would push it higher.

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 followed by key details. No wasted words; 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 explicitly lists all return components (overall score, tier, verdict, sub-scores, tech-stack hint, SEC summary). It also explains the tuning by buyer profile and the optional filings parameter. The description is complete enough for an agent to invoke correctly, though it lacks edge-case or error-handling 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema; it mentions buyer_profile values and include_filings, but the schema already explains these. No additional parameter semantics are provided.

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 computes a composite B2B buyer-signal score (0-100) for a company, specifying the data sources (identity, SEC EDGAR, DNS/DMARC, WHOIS, hiring signals) and the output. This distinguishes it from siblings like compliance_signal or company_enrich by focusing on buyer intent.

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 what the tool is for (buyer signals tuned by buyer_profile) and its output, making it obvious when to use it. However, it does not explicitly exclude alternatives or mention when not to use it, which would be needed for a perfect 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 declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds value beyond those by disclosing the behavioral trait that it returns only aggregate counts (not entity-level data) across defined facets, and that the registry is 3.3M entities. No contradictions with annotations.

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

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

Two tightly written sentences. The first front-loads the action and resource, the second specifies filter parameters. No filler 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 adequately conveys the return nature (aggregate counts per facet) and the available filters. It does not detail the exact output structure or what 'hierarchy/data-quality coverage' includes, but for a stats tool with safe annotations 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?

Schema description coverage is 100%, so the baseline is 3. The tool description goes further by explaining the role of country/jurisdiction/industry/naics as slice filters, and implicitly clarifies that entity_type, employee_range, and decade founded are facet dimensions rather than filter parameters — useful semantic context beyond the individual property descriptions.

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

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

The description opens with a specific verb and resource: 'Return aggregate counts across the 3.3M-entity registry,' and enumerates the exact facet dimensions (country, jurisdiction, industry, entity_type, employee_range, decade founded, plus hierarchy/data-quality coverage). This clearly distinguishes it from sibling tools like company_enrich or company_search, which return individual entity data rather than aggregations.

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 this tool is appropriate: when aggregate counts over the registry are needed, not individual records. It also gives filter usage ('Filter the slice with country/jurisdiction/industry/naics'), but does not explicitly name alternatives or state when-not-to-use, so it stops 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 the tool read-only, idempotent, and non-destructive, so the description does not need to restate safety. The word 'loaded' hints at a pre-built snapshot, but it is too vague to disclose meaningful behavior such as data freshness, failure modes, or 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 a single short sentence with the action and resource front-loaded. It contains no filler or redundant restatement of the input schema, making it easy for an agent to scan.

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 leaves the contents of a 'company profile' undefined, so an agent cannot know whether it returns identifiers, fundamentals, ownership, or summary data. Given the large sibling family, this missing specificity is a significant gap for a tool whose only parameter is already fully documented.

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 documents the single ticker parameter and even gives 'NVDA' as an example, so schema coverage is 100%. The description only restates 'by ticker' and adds no format, alias, or usage 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 states a specific action ('Return') and resource ('curated company profile') keyed by public ticker, so an agent can tell it is a lookup tool. However, it does not distinguish company_ticker from adjacent siblings such as company_enrich, company_search, or equities_ticker, and the qualifier 'loaded' is ambiguous.

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 about when to use this tool instead of the many sibling company/equities tools, and no alternative tools are named. The phrase 'curated company profile' hints at a use case but does not establish selection criteria or exclusions.

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 communicate that the tool is read-only, idempotent, open-world, and non-destructive. The description adds useful content-level context, such as SEC former-name rebrand events and parent disclosures, but it does not disclose behavior around the three optional identifiers, such as precedence when multiple are provided or whether the list is ordered differently.

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 the core concept front-loaded before the em dash and supporting examples after. Every element earns its place, and there is no redundant 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 read-only event-list tool without an output schema, the description names the expected output categories well enough for an agent to understand what it returns. It does not cover disambiguation behavior among the three optional resolvers, but the schema and annotations already cover parameter and safety aspects, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds no parameter-specific semantics beyond what the input schema provides, so the baseline score 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 clearly identifies the resource (a chronological lifecycle event list for a company) and names specific content: founding year, SEC former-name rebrand events, current status, and parent disclosures. It is specific enough to convey the tool's purpose, though it does not explicitly differentiate it from siblings like company_enrich or company_change.

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 used to obtain a company's lifecycle events, but it provides no explicit when-to-use guidance or alternatives. With a large sibling list including company_change, company_insights, and company_enrich, an agent is given no criteria for choosing this tool over others.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond those by revealing data sources, output semantics, profile-dependent tuning, and the decision-support boundary. It does not fully describe edge cases such as unknown companies or data freshness, but those are less critical given the existing 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, front-loaded with the core purpose, uses a clear output list, and ends with a scannable scope warning. Every sentence provides selection- or invocation-relevant information, with no wasted words.

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

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

With no output schema, the description names the key return elements and decision_hint values, which is essential and mostly sufficient. It could specify more about critical flags and resolution behavior when multiple identifiers are provided, but the core invocation information is present and openWorldHint supports partial or unstructured responses.

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% and the schema already explains company/domain/ticker resolution. The description adds meaning to buyer_profile by enumerating the tuning contexts (kyc_onboarding, vendor_diligence, regulated_industry, marketplace_listing), which the schema only lists as an enum. It does not add much beyond the schema for the identifier parameters, so not a 5.

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 'Compliance-status snapshot for a company' and names concrete data sources (Treasury OFAC SDN, SEC enforcement) and output fields (0-100 score, tier, decision_hint, critical flags). This clearly differentiates it from sibling tools like sanctions_search or company_signal by emphasizing a scored snapshot rather than raw search or general enrichment.

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 states when to use the tool (decision-support compliance snapshots for company screening) and explicitly scopes out formal KYC or licensed sanctions screening, which is a clear when-not. It also ties usage to specific buyer profiles, indicating the contexts in which the tool is tuned.

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 important behavioral context beyond annotations: it joins multiple live data sources, returns a 0-100 score where higher means lower risk, and emits a decision_hint mapped to specific credit actions. It does not disclose failure modes or data freshness details, but the annotation coverage lowers the burden.

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 dense but well-organized: it leads with the business question, then the composite inputs, then the output semantics, then the profile variation. Each sentence adds substantive information, though the middle sentence packs multiple clauses and enumerated values that could be slightly easier to parse.

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 composite tool with no output schema, the description does a good job of explaining the output shape and score direction. However, it leaves gaps: the risk_profile values are not explained, include_filings is never mentioned, and there is no guidance on what happens when domain or ticker cannot be resolved.

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 50%, with risk_profile and include_filings effectively undocumented in the schema. The description only says the tool 'supports four risk profiles for different underwriting postures' without explaining the individual enum values or the effect of include_filings, so it fails to compensate for the schema 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 opens with an explicit business question ('should we extend terms to this company?') and names the tool as a counterparty-risk composite producing a score, tier, and decision_hint. It clearly distinguishes this from sibling data-lookup tools by tying the output to concrete AR/AP actions.

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 gives clear context for when to use the tool ('should we extend terms') and mentions four risk profiles for 'different underwriting postures'. It does not explicitly name alternative sibling tools or state when not to use them, but the credit-decision framing is a sufficiently clear usage context.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: the score scale semantics ('higher = lower risk'), the exact components returned, the 'Tuned by buyer profile' behavior, and the hard scope limitation to published DNS with explicit non-actions. This is valuable and consistent with 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-loads the core purpose in the first sentence, and packs output details, score interpretation, and scope constraints into a compact structure. Every sentence adds distinct value with no repetition 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?

Even though there is no output schema, the description fully characterizes what the caller should expect: a 0-100 score with directionality, six named sub-scores, critical flags, recommended actions, and buyer-profile tuning. It also states the operational scope and exclusions, giving an agent enough context 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 50%: 'domain' has a description but 'buyer_profile' does not. The description adds that the result is 'Tuned by buyer profile,' which gives the parameter purpose beyond the schema enum/default. However, it does not explain how different buyer_profile values affect the score or which profiles exist, leaving the undocumented parameter only partially clarified.

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 as assessing a 'DNS-hygiene + tech-stack-exposure surface' for a domain and explicitly states the output: a 0-100 cyber score, six sub-scores, critical flags, and recommended actions. This distinguishes it from sibling DNS tools like dns_lookup or dns_profile by emphasizing the risk-signal output rather than raw DNS 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 provides clear context on what the tool covers and explicitly states exclusions: 'inspects published DNS only — no port scans, breach lookups, or CVE matching.' It also notes the score is 'Tuned by buyer profile,' indicating when parameter customization matters. However, it does not name specific sibling tools or state explicit when-to-use 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 this as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations by naming the external source (crt.sh), stating the output fields, and noting deduplication of subdomains across CT entries. It stops short of caveats like data freshness or pagination, but this is sufficient for a read-only lookup.

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, front-loaded with the core function and source, and each sentence earns its place. Use cases are deferred to the end, keeping the most operationally relevant information first.

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 conveys the tool's purpose, external source, and main output components, and the schema documents the required domain and optional limit. However, with no output schema and no parameter explanation, an agent is left to infer how the limit affects results and exactly what the returned structure looks like. 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 0%, and the description does not explain the meaning or interplay of the domain and limit parameters. The domain parameter is implied by the domain-focused output, but limit is never mentioned, so the description adds no value beyond the raw input schema.

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

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

The description explicitly states the tool returns SSL certificates from Certificate Transparency logs, including issuer, expiry, and a deduped subdomain list. This clearly differentiates it from sibling DNS tools by naming its data source and unique subdomain extraction behavior.

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 openly lists concrete use cases: shadow-IT detection, sales-intel hostname discovery, and phishing-cert monitoring. It provides clear context for when the tool is valuable, though it does not explicitly say when not to use it or name alternative 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 signal readOnly/idempotent/non-destructive, and the description adds valuable behavioral specifics: the computation includes edit distance, apex/TLD diff, and homoglyph substitution with concrete substitutions, and the result flags are is_likely_typosquat and is_likely_lookalike with drivers. Stating 'no DNS query' clarifies there are no network side effects, which is beyond annotation semantics.

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

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

Three sentences deliver the purpose, the algorithmic internals, and the key caveat without filler. The most selection-relevant information (compare, no DNS query) is front-loaded.

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

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

Given there is no output schema, the description usefully names the output flags and drivers, plus the computed dimensions. It doesn't fully specify the response shape or define 'drivers,' but for tool selection and invocation the inputs, outputs, and side-effect boundary are sufficiently 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 already documents both parameters with descriptions and examples (target: 'Suspect domain, e.g. striipe.com'; reference: 'Known-good domain, e.g. stripe.com'), and description coverage is 100%. The description merely mirrors this relationship rather than adding new constraints, formats, or default 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 names a specific action ('Compare a target domain against a reference') and a concrete detection purpose (phishing/typosquatting/lookalike). It distinguishes dns_compare from the many dns_* siblings by closing with 'Pure analytical comparison — no DNS query,' so an agent can select it without opening schemas.

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

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

Explicitly frames this as pure analytical comparison and rules out DNS querying, which prevents confusion with dns_lookup/dns_history/dns_profile. It neither lists alternatives by name nor gives a when-not-to-use rule (e.g., 'for resolution use dns_lookup'), but the exclusion plus sibling context supplies adequate guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations by explaining the snapshot-on-query semantics, the data provenance ('accumulates from when our users first resolve a domain'), and the implication that results are not a complete global DNS history.

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

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

Three compact, information-dense sentences. The core behavior is front-loaded, followed by practical use cases and a key limitation. No filler or repetition of schema fields.

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?

Despite having no output schema, the description enumerates the returned fields (record_type, value, first_seen, last_seen, observation_count), which is sufficient for basic use. The main completeness gap is the unaddressed limit_per_type behavior, but overall this is a well-specified tool for a simple three-parameter query.

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 record_type has an inline description. The description mentions 'this domain' and 'record_type' but does not compensate for limit_per_type, which is undocumented in the schema and unmentioned in the description. The phrase 'Returns every tuple' also conflicts with the existence of limit_per_type, potentially misleading the agent about result completeness.

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 and resource: 'Snapshot-on-query passive-DNS view' that 'Returns every (record_type, value) tuple seen for this domain.' It clearly distinguishes itself from siblings like dns_lookup and dns_profile by emphasizing the historical, observed nature and its accumulation from /dns/lookup calls.

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 concrete use cases: 'detecting when A records moved or recovering historical NS/MX values,' and a clear exclusion: 'Not a global feed — accumulates from when our users first resolve a domain.' It does not explicitly name alternative sibling tools, but the context and limitations are clear enough for routing.

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 is consistent with the annotations (readOnlyHint, idempotentHint, destructiveHint=false) but adds no behavioral context beyond them. It does not mention default behavior, caching, response shape, or error conditions. The annotations carry the safety profile, but no extra transparency is provided.

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 with no unnecessary words, front-loading the verb and the full list of supported record types. It is immediately scannable and contains 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 two-parameter read-only lookup, the core usage is clear, and the annotations cover the safety profile. However, the description does not state what happens if 'types' is omitted, and there is no output schema to clarify the return structure. Sibling tools cover related DNS areas, so a brief scope statement 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 already documents both parameters with 100% coverage. The description adds value by listing the valid record types for the 'types' parameter, which the schema only describes generically as 'comma-separated record types.' It does not explain defaults or exact formatting beyond that.

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 ('Resolve') and clearly names the resource: DNS records for a domain, enumerating exact record types. It is easy to tell this is a current DNS lookup tool, though it does not explicitly contrast with sibling tools like dns_history or dns_profile.

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

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

No guidance is provided about when to use dns_lookup versus siblings such as dns_history, dns_compare, or dns_profile. The phrase 'resolve records' implies current-record lookup, but there are no explicit exclusions or alternative routing instructions.

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 behavioral context beyond that by disclosing that the tool performs subdomain probing and produces a health verdict, which implies active enumeration and synthesized judgment. It does not mention latency or cost, but it provides meaningful disclosure of the tool's composite 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?

One dense, front-loaded sentence communicates the full scope and workflows with no filler. Every element 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?

For a three-parameter composite tool with no output schema, the description provides sufficient context for an agent to select and invoke it correctly. It enumerates all major data domains and gives workflow context. The main gap is the lack of explicit treatment of the skip parameters and the exact nature of the health verdict, but this does not critically impair usage.

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

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

Schema description coverage is 0%, so the description must compensate. The required 'domain' parameter is self-evident, and 'skip_whois' and 'skip_subdomains' are reasonably inferable from their names and from the WHOIS/subdomain-probe components mentioned in the description. However, the description does not explain how skipping affects the overall profile or health verdict, leaving some 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 produces a comprehensive DNS + WHOIS + security + hosting + email-infrastructure + subdomain-probe + health-verdict profile for a domain in one call. This distinguishes it from narrower sibling tools like dns_lookup, dns_whois, and dns_reputation.

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 identifies concrete workflows ('Sales-intel and security-audit workflow') and emphasizes 'one call', clearly implying this tool is for broad investigative use cases rather than single-aspect DNS queries. It does not explicitly name alternative tools or exclusion conditions, but the use context is clear.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds meaningful behavioral context by revealing the calculation inputs, the 0-100 scale, and the band outputs, without contradicting the annotations. It stops short of disclosing potential latency, data freshness, or error conditions, but the annotation coverage lowers the burden.

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: the first front-loads what the tool computes and returns, the second adds a clear use case. No filler, repeated schema content, or vague boilerplate. Every clause earns its place.

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

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

With no output schema, the description adequately describes the return value (score, band, contributing factors) and the input context. It covers the main behavioral scope and use case for a single-parameter read-only tool. Slight gaps remain around domain input formatting and edge-case behavior, but nothing critical for a fraud-screening call is missing.

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 carries the burden, but the only parameter (domain) is self-evident from the tool name and schema. The description refers to 'domain age' and the overall purpose, implicitly confirming the input is a domain, yet it adds no format details (e.g., no protocol, punycode, or subdomain handling). This is adequate but not compensating 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 clearly states the tool returns a composite 0-100 reputation score for a domain, listing the specific factors (domain age, registrar tier, expiration window, security grade, NS diversity, hosting tier) and outputs (band + contributing factors). This verb+resource+scope formulation distinguishes it from siblings like dns_lookup or dns_whois, which are unlikely to produce a scored band.

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 'Designed for fraud-screening pipelines' gives clear intended use context, signaling when an agent should pick this tool (domain reputation assessment for fraud risk). It does not explicitly name alternatives or when not to use it, but the context is specific enough to guide selection among the many sibling DNS/site/risk 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations: that it actively initiates a network handshake and grades the result, plus what findings it surfaces. This helps the agent understand the real-world side effect despite readOnlyHint.

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, front-loaded sentences with no filler. The first sentence states the core operation and outputs, the second lists key surfaces. Every clause earns its place.

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

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

With no output schema, the description explains the main returned fields (expiry, SAN, self-signed, findings, grade). Annotations cover safety, and the input schema covers the port range and default. It is complete enough for selection and basic invocation, though parameter semantics could be stronger.

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 bears the burden of explaining parameters. It mentions ':443' but does not clarify that 'port' is an overridable parameter or describe that 'domain' is the target hostname. The only parameter it implicitly addresses is the default port, leaving the required domain parameter essentially unexplained.

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 ('Open a TLS handshake'), the resource (port 443), and the specific data captured (cert, protocol version, cipher, A-F grade, expiry, SAN, self-signed detection). This clearly distinguishes it from sibling tools like dns_lookup or dns_certificates, which are not live handshakes.

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 conveys that this is a live, active check by explicitly saying 'Open a TLS handshake on :443', implying it is for current TLS posture rather than historical or registry-based DNS data. It does not name alternatives or exclusions, but the live-handshake framing provides clear context for when to use it.

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, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by specifying the exact response fields and the computed 'age in years', which is valuable because no output schema exists. It does not detail failure modes such as unknown domains, but this is a minor gap for a simple read-only lookup.

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 delivers the key semantic content upfront: it is public WHOIS data, followed by the returned fields. There is no wasted wording or irrelevant detail.

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 one-parameter read-only tool with complete annotations and an in-description output field list, the description is largely complete. The only notable omission is guidance on when to prefer a sibling DNS/WHOIS tool, but that is a routing concern rather than a calling-context 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 single parameter 'domain' is fully described in the schema with an example, so schema coverage is 100%. The description mentions WHOIS data but does not add any extra meaning 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 states a clear resource ('Public WHOIS profile') and enumerates the data returned: registrar, creation date, expiration, name servers, and age in years. It is easy to understand what the tool does, though it lacks an explicit verb and does not differentiate itself from dns_profile or dns_lookup among the 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?

There is no guidance about when to use this tool instead of siblings such as dns_profile, dns_history, or dns_lookup. An agent must infer the intended use from the name and description, with no exclusions or explicit conditions.

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 a useful behavioral nuance — the result is a membership test against a 'curated' list, implying outcomes can evolve as the list changes — but it does not disclose return shape, fallback behavior, or list refresh semantics. 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?

A single sentence that front-loads the action verb 'Test' and carries only the essential scoping detail ('curated disposable-email-domain list'). Every word earns its place; there is no redundant boilerplate.

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 one-parameter, read-only, idempotent membership check, the description is largely sufficient for correct invocation: the input is clear and the test criterion is explicit. Minor gaps remain — there is no output schema to imply the return format, and the description does not differentiate itself from the closely named email_free_provider sibling — but these are small for a tool of this 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 description coverage is 100%, and the schema already documents 'domain' as 'Domain to test, e.g. mailinator.com.' The description's mention of 'domain' adds no meaning beyond the schema; it neither clarifies edge cases (e.g., whether full emails are accepted) nor enriches the parameter semantics, 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 states a specific verb ('Test'), resource ('domain'), and the exact criterion ('belongs to the curated disposable-email-domain list'), which clearly conveys what the tool does. It is distinguishable from siblings like email_validate and email_smtp_probe by the unique 'curated disposable-email-domain list' object, though it never explicitly names or contrasts a sibling (closest is email_free_provider), so it stops short of a 5.

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: invoke when you need to determine whether a domain is on the disposable-email list. However, there is no explicit guidance on when to choose this over the adjacent email tools (email_free_provider, email_validate, email_smtp_probe), and no exclusion statements or alternative routing.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the 'curated' qualifier, which implies the list is maintained and possibly non-exhaustive—useful context beyond annotations. However, it does not disclose edge cases, return format, or what happens with invalid domains.

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 ('Test whether') and the object ('domain') followed by the precise list qualifier. There is no filler or redundant phrasing; 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?

For a one-parameter, boolean-style lookup with annotations covering safety, the description conveys the core behavior adequately. It could mention that it returns a boolean or doesn't handle full email addresses, but 'Test whether a domain belongs' strongly implies a boolean result and the scope is clear. Minor gap, but not critical.

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 already explains 'Domain to test, e.g. gmail.com.' The tool description adds no extra meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Test whether'), a clear resource ('domain'), and a precise criterion ('belongs to the curated free consumer-email-provider list'). It distinguishes this tool from siblings like email_disposable (disposable domains) and email_validate (general email validation) by highlighting the curated provider-list 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 makes the purpose clear but does not explicitly state when to use this tool over alternatives such as email_disposable or email_validate. Usage context is implied ('free consumer-email-provider') but no exclusions or alternative routing 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 mark readOnly/idempotent/nondestructive, and the description adds materially: no DATA, catch-all detection via random-fake-RCPT comparison, automatic skip for specified providers, and ~3-8s latency. This gives the agent useful behavioral expectations 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?

Four compact sentences, each carrying distinct information: mechanism, output, catch-all method, provider exemptions, and latency. Core action and output are front-loaded with 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?

With no output schema, the description still enumerates the possible verdicts, explains the probing protocol, discloses provider skips, and gives latency. That is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema documents only email; check_catch_all is a bare boolean. The description adds meaning to catch-all behavior via 'random-fake-RCPT comparison' and the auto-skip caveat, but it never explicitly names check_catch_all or states that it can be disabled, so the compensation is 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?

States a specific verb and resource: 'Live SMTP RCPT probe (HELO + MAIL FROM + RCPT TO; no DATA)' with a concrete output enum. The protocol detail and verdict list distinguish it from sibling email/address validation tools even without naming an alternative.

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 use for live SMTP deliverability checking, includes catch-all detection, and notes automatic skipping for major providers. It does not explicitly name alternatives or state when not to use it, so it has strong contextual guidance but no formal exclusions.

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 meaningful behavioral context beyond that: it performs MX lookup, flags disposable/free/role accounts, suggests typo corrections, returns a composite score, and importantly does NOT perform a live SMTP probe. It also notes demo mode is allowed, which is useful operational context not captured in 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 compact sentence that front-loads the core action and then efficiently lists the key checks and limitations. Every clause adds information: the validation scope, the behavioral boundary (no SMTP probe), and the demo-mode allowance. There is 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?

The description is adequate for a moderately complex read-only tool: it explains what checks are performed and the composite score, and the annotations cover safety. However, with no output schema, the description does not fully characterize the return shape beyond the score/flags, and the check_dns parameter remains unexplained. These gaps make it complete enough to use but not fully self-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 description coverage is only 50%: 'email' is described, but 'check_dns' has no schema description and no description-level explanation. The description mentions 'MX lookup' but never links it to the check_dns parameter or explains that toggling check_dns controls DNS checking. With one undocumented parameter and no compensating explanation, the description fails to fully convey parameter semantics.

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

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

Description states a specific verb ('Validate') and resource ('an email address') and enumerates exactly what the validation covers: RFC syntax, MX lookup, disposable/free/role-account flags, typo correction, and composite deliverability score. This clearly distinguishes it from sibling tools like email_smtp_probe or email_disposable by positioning it as the comprehensive validation entry point.

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 by presenting it as full email validation and by explicitly noting 'no live SMTP probe,' which hints that live probing is out of scope. However, it does not name sibling alternatives such as email_smtp_probe for live deliverability checks or email_disposable/email_free_provider for narrower checks, so usage guidance remains 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?

With readOnlyHint, idempotentHint, and non-destructive annotations already present, the description leverages that coverage and adds behavioral context: 'Returns every observation across every reported unit, most-recent first.' This tells the agent about completeness and ordering without needing to re-state safety. 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?

Two sentences front-load the core behavior, then usage, then ordering, with no waste or repetition. Every sentence adds value and the structure is easy to parse.

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, usage, and ordering, but because there is no output schema it does not describe what an observation record contains (e.g., date, value, filer). The unexplained include_segments parameter is another gap, leaving an otherwise simple tool slightly incomplete 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?

Only concept has schema documentation, and the description merely echoes 'any us-gaap tag' without adding format details. ticker is left as a bare string with no accepted format, and include_segments has no explanation in either the schema or the description. Given 33% schema description coverage, the description fails to compensate for two of the three 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 opens with 'Full observation history for one XBRL concept (any us-gaap tag)', naming the specific verb, resource, and scope. It also explicitly differentiates the tool from the '35-item headline catalog', clarifying its niche among siblings. The title reinforces the same content.

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

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

The sentence 'Use for fields outside our 35-item headline catalog' explicitly states when to choose this tool and implicitly excludes catalog fields. However, it does not name the alternative tool (e.g., equities_fundamentals) that provides the catalog, so the alternative remains 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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is fully transparent. The description adds the 'live' nature and the focus on 'most recent' filings, which is helpful, but it does not disclose response shape, pagination, or rate-limit behavior. This is acceptable given the strong annotation coverage but not exceptional.

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 that front-loads the core behavior and then adds the key filtering capability. No wasted words.

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

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

For a simple read-only tool with four parameters and no nested output schema, the description plus annotations cover the essential invocation context. The main gap is the absence of any hint about the response format, but the tool's simplicity and strong annotations make this a minor omission.

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%, and the description adds relationships that the schema does not: 'for a ticker or CIK' clarifies the mutual-exclusivity between cik and ticker, and 'filter by form type' maps directly to the forms parameter. This goes beyond simply restating the schema fields.

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 and resource: it returns live SEC EDGAR submissions (10-K, 10-Q, 8-K, ...) for a ticker or CIK, with optional form-type filtering. This makes its purpose unmistakable and distinguishes it from sibling tools like equities_fundamentals 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 clearly implies when to use this tool: when you need recent SEC filing data for a company identified by ticker or CIK, and optionally filtered by form type. It does not explicitly name alternative tools or exclusion criteria, but the use case is specific enough for an agent to route correctly.

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 read-only, idempotent, non-destructive profile, so the description only needs to add context. It adds the SEC XBRL companyfacts API as the source and notes the tool is free, which is useful. However, it does not discuss data limitations, units, or the shape of returned periods, leaving a moderate gap.

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 compact sentences with no filler. The action and resource are front-loaded, the key metrics are listed in a readable series, and period selection plus free/source context are added efficiently. Every clause earns its place.

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

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

For a simple read-only tool with strong annotations, the description plus schema defaults and enums provide enough to call it correctly. The absence of an output schema is mitigated by the metric list, though minor ambiguity around 'limit' and return structure remains.

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%, so the description partially compensates by explaining period values (annual = 10-K, quarterly = 10-Q) and listing the kind of metrics returned. It does not clarify the meaning of 'limit' (e.g., number of periods vs. number of tags) or ticker formatting, so parameter understanding is incomplete.

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 ('parsed from SEC XBRL filings') and a specific resource (headline financial statements), listing concrete metrics and the annual/quarterly distinction. It is clear and actionable, though it does not explicitly distinguish itself from sibling tools like equities_filings or equities_concept.

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 summary fundamentals via 'headline financial statements' and 'curated tags,' but it never states when to use it over alternatives or when not to use it. There is no mention of sibling tools or exclusions, leaving the agent to infer routing.

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 covered. The description adds the SEC EDGAR registry source and enumerates exactly what the lookup returns, giving useful beyond-annotation context about the tool's behavior and result content.

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 contains all essential information: the action, the input, the output fields, and the data source. There is no filler or redundancy, and every phrase contributes to the agent's understanding.

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 lookup with one required parameter and no output schema, the description sufficiently specifies the inputs and the main return fields. It could be slightly stronger by adding edge-case behavior (e.g., unknown ticker) or disambiguating from company_ticker, but overall it is complete for its complexity.

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

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

The input schema already provides 100% coverage with a clear description for the only parameter ('Stock ticker, e.g. AAPL.'). The tool description does not add extra parameter-level 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 ('Resolve') and names a clear resource (stock ticker) with concrete outputs: company name, CIK, exchange, SIC industry code, and headquarters. It also identifies the data source (SEC EDGAR registry), making the tool's scope distinct from siblings like equities_filings or 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 implies the primary use case: when you have a ticker and need company identity metadata from SEC EDGAR. However, it does not explicitly state when to choose this tool over similar siblings such as company_ticker or company_cik, nor does it provide any exclusions or alternative routing 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 mark it read-only, idempotent, and non-destructive; the description adds the useful notion that signals are 'loaded' rather than live. It does not contradict annotations, but it does not disclose output shape or aggregation details beyond the word 'summarize'.

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 with the core verb and scope front-loaded. Minor jargon like 'loaded' could be clarified, but there is no waste.

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 one-parameter tool with strong safety annotations, so the description need not carry much. However, with no output schema and several flight siblings, it would benefit from clarifying what a 'summary' contains and how this differs from flight_reliability.

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 documents airline_code ('Carrier code, for example DL') and the description only restates the carrier-code scope. No extra input semantics are added beyond what the schema already provides.

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

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

The description states a specific verb ('Summarize') and resource ('loaded route reliability signals') scoped to a carrier code, so it avoids tautology. It does not explicitly compare itself to the closely named sibling flight_reliability, so it is clear but not fully differentiating.

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 text indicates when to prefer this tool over flight_reliability, flight_route_summary, or other flight siblings. The only implied context is 'carrier code', which describes the parameter more than the decision situation.

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), so the bar is lower. The description adds minimal behavioral context beyond the annotations, only hinting at aggregation scope with 'route aggregates.' It does not describe output format, time coverage, or reliability metrics.

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 short and starts with the main verb, which is good. However, the repeated word 'loaded loaded' and the unclear term 'route aggregates' make it less polished and precise than it could be.

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

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

Given the tool has a single well-documented parameter and rich annotations, the description is not severely incomplete. Yet the lack of an output schema and the cryptic 'loaded loaded route aggregates' leave ambiguity about what signals are actually returned, so more context would help.

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 only parameter, airport_code, is fully documented in the schema with an example (ATL). The description itself adds nothing about parameters, but with 100% schema coverage the schema carries the burden, so the 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 uses a clear verb ('Summarize') and identifies the resource ('an airport') and the subject ('delay and reliability signals'), which differentiates it from airline- or route-level flight tools. However, the phrase 'across loaded loaded route aggregates' is vague and contains a typo, which slightly obscures the exact 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 implies this tool is for airport-level delay/reliability summaries, which gives some basis for selecting it over flight_route_summary or flight_airline_reliability. But it does not explicitly state when to use it or exclude other flight-related siblings, leaving the choice somewhat to inference.

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. The description adds useful temporal context with 'historical' and 'not live tracking,' but it does not disclose the signal format, lookback period, or granularity, so some behavioral detail remains implicit.

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 short sentences with no filler. The first sentence states the core capability, and the second sentence prevents misuse by clarifying this is not live tracking. 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 only two required parameters, and annotations cover safety semantics. However, because there is no output schema, the description should clarify what 'signals' actually look like, such as fields, units, or possible values, which is currently left to inference.

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

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

Schema description coverage is 100%, so the parameters are already documented fully in the schema. The description adds no parameter-specific meaning beyond routing, which is acceptable under the baseline for fully covered schemas.

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

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

States a specific verb ('Return'), resource ('historical cancellation-risk signals'), and scope ('for a route'). The phrase 'not live tracking' distinguishes it from live flight-status tools and implies it is not a real-time tracker, separating it clearly from sibling flight 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?

Provides a clear use case: obtaining historical route cancellation-risk signals. It also gives an explicit when-not boundary with 'This is not live tracking.' It does not name alternatives like flight_reliability or flight_route_summary, so it stops short of full routing 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the demo-mode restriction, which is a genuine behavioral trait beyond annotations. But it does not clarify what 'reliability' means as a metric, what happens for unsupported routes, or the historical date range 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 two sentences and front-loads the core purpose before the constraint. The route list is somewhat long but carries necessary demo-mode information. Nothing is wasted, though the enumeration could arguably be condensed.

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 query tool with only three well-documented parameters and safety annotations, the description covers the basics. However, there is no output schema, so the agent must infer what a reliability result looks like; the meaning of the reliability metric and the behavior on unsupported routes are also left unspecified. Adequate but with 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 coverage is 100%, so the baseline is 3. The description adds value by listing concrete origin-destination pairs (ATL-LGA, ORD-EWR, etc.) that are actually loadable in demo mode, which tells the agent which parameter combinations will succeed beyond the schema's generic format examples. This justifies one point 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 opens with a clear verb-plus-resource statement: 'Return historical route reliability.' The word 'route' helps separate it from the sibling flight_airline_reliability. However, it does not explicitly distinguish itself from overlapping siblings like flight_cancellation_risk, flight_route_summary, or flight_route_best_times, so it stops short of full differentiation.

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

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

The description provides operational context by noting that 'Demo mode allows selected loaded routes' and enumerates the six supported route pairs. This implies when the tool can actually return data in demo environments, but it never states when to prefer this tool over the related flight tools or what conditions would select an alternative.

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, covering safety. The description adds a small behavioral detail: it ranks buckets by 'historical reliability score', implying a sorted output, but does not describe the return format, pagination, or what 'loaded' means. Given the annotations, this is adequate but not rich.

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 action ('Rank loaded departure-hour buckets') and the basis ('historical reliability score'). No filler or redundant information; every word contributes.

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 required parameter) and the schema plus annotations cover the input and safety. However, there is no output schema, and the description does not specify what the return value looks like (e.g., a ranked list of hours with scores). More detail on the output would improve completeness, but the low complexity makes it 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?

The schema fully describes the single 'route' parameter with format and example, achieving 100% schema coverage. The description merely refers to 'a route' without adding new meaning. Baseline of 3 is appropriate since the schema carries the parameter semantics.

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

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

The description clearly states the verb 'Rank' and the resource 'loaded departure-hour buckets for a route' based on 'historical reliability score'. It is specific and distinct enough from siblings like flight_route_summary or flight_reliability, though it does not explicitly name them. The purpose is evident.

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 guidance on when to use this tool versus alternatives. There is no mention of scenarios, exclusions, or comparisons to other flight-related tools, so an agent must infer the appropriate context from the name and description alone.

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 covered. The description adds 'historical' and 'not live tracking,' which adds context about the temporal nature of the data. But it doesn't disclose how missing data is handled, what 'best time bucket' means, or any rate limits. With annotations carrying the safety profile, the description provides minimal but useful additional 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 exactly two sentences with zero redundancy. The first sentence front-loads the primary purpose and content, and the second sentence is a concise clarification. 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?

For a simple two-param tool with safe annotations, the description lists the key output components, which is helpful. However, it omits any mention of the output format (since no output schema exists), and given the large number of flight siblings, it doesn't explicitly explain when this combined view is more appropriate than the focused tools. It is adequate but not comprehensive.

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 both parameters (origin, dest) are already described as airport codes with examples. The description doesn't add extra meaning beyond 'route,' such as format enforcement or coordinate vs. code. Since the schema fully documents the parameters, the description does not need to compensate, earning the baseline 3.

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

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

The description uses a specific verb ('Return') and resource ('combined historical route summary'), and lists the included data points (reliability, cancellation risk, carriers, months, best time bucket). It distinguishes from live tracking, which helps set expectations. However, it doesn't explicitly differentiate from sibling tools like flight_reliability or flight_cancellation_risk, though the word 'combined' implies aggregation.

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 only usage hint is 'This is not live tracking,' which is a negative clarification but offers no guidance on when to choose this tool over the many flight-specific siblings (e.g., flight_airline_reliability, flight_route_best_times). No explicit conditions or alternatives are mentioned, leaving the agent to infer that the combined summary is preferable for a holistic view.

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, non-destructive, and idempotent behavior. The description adds useful behavioral context by specifying the output's content categories and its role as a catalog, which is relevant beyond the annotation hints.

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

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

Two sentences, each earning its place: the first defines the output content, the second states the intended use. It is succinct, front-loaded, and contains 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 zero-parameter catalog with no output schema, the description adequately covers return expectations by listing the key fields and explaining why an agent would call it. Nothing essential is missing for correct invocation.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description reinforces that this is a catalog rather than a parameterized query, adding meaning without needing parameter-level explanations.

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 names the specific resource (curated FRED series shortcuts) and enumerates the content fields (FRED ID, title, units, frequency). It explicitly connects to fred_series for slug discovery, which helps distinguish it from sibling search 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 gives clear usage context: 'Use this catalog to discover what slugs are available for fred_series.' It does not explicitly mention alternatives or exclusions like fred_search, but the downstream relationship is clear enough for an agent to route correctly.

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, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by stating 'Ordered by popularity,' which informs the agent of the result ordering. It also implies a search behavior (free-text) that is not explicit in 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?

Two sentences with no filler. The purpose and usage are front-loaded, and the example is compact and illustrative. 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?

For a simple two-parameter search tool with annotations covering safety, the description is complete. It clarifies the query semantics, ordering, and typical use case. No output schema is present, but the agent can infer the return is a list of series without extra detail. Nothing critical is missing.

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 should compensate. It explains q via example ('q='initial jobless claims''), illustrating its use, but does not describe the limit parameter at all. Limit is self-explanatory (a max count), but since coverage is zero, the description leaves a gap. It partially compensates for q but not limit, warranting a mid-range score.

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

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

The description clearly states the tool performs a free-text search of FRED's ~800k series catalog, ordered by popularity. It includes a concrete example (e.g., 'initial jobless claims') that illustrates the query type. It distinguishes itself from siblings like fred_series (which likely operates on a known ID) and fred_popular (which may list popular series without search), making the 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 explicitly says 'Use when you don't know the series ID,' giving a clear trigger condition. It does not name the alternative tool (e.g., fred_series) but implies that when the ID is known, a different tool should be used. The guidance is actionable but stops short of explicitly contrasting with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful operational context beyond annotations: the upstream is free, a server-side key is required, and the tool covers roughly 800k series across major data sources. It does not describe response format or pagination, but this is less critical given the rich 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, front-loaded with the core action, and every sentence earns its place. The examples are inline and the coverage/key-requirement details are relevant operational context. There is no fluff or repetition of schema 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 tool with no output schema, the description could say more about the response structure, units, or default time range. However, the name and 'time-series' wording make the return type clear enough, and the description covers input alternatives, scale of data, source coverage, and the server-side key requirement. It is adequate for correct invocation, with only minor gaps around output 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?

The description significantly enriches the main parameter series_or_slug by listing many example slugs and clarifying the raw-ID alternative. However, schema description coverage is only 60%; sort and limit have no description in the schema and the tool description does not explain their semantics either. The main parameter is well handled, but 40% of the schema is left without added meaning.

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 action and resource — 'Fetch any FRED time-series' — and clearly scopes the tool to retrieval via curated slug or raw FRED ID. Concrete examples ('gdp', 'CPIAUCSL') make the operation unambiguous and distinguish it from sibling tools like fred_search and fred_popular, which are about discovery rather than direct series fetching.

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 right usage — call this tool when you already have a slug or raw FRED series ID — but it does not explicitly say when to prefer fred_search or fred_popular instead. There is clear context on input forms, but no direct when-to-use/when-not-to-use routing.

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 valuable context beyond that by stating it pulls live from EDGAR, uses recency weighting, and returns specific cadence categories. 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 compact and front-loaded with the core behavior and output categories. The opening clause is somewhat redundant with the title, but the remaining sentences are dense and useful.

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 usefully communicates the data source, output concepts, and profile-specific behavior. Still, the semantics of limit and window_days and a more precise return shape are absent, so it is 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 descriptions cover domain and ticker, and the description adds meaning for buyer_profile by enumerating its tuning values. However, limit and window_days are never explained in the description, and with only 40% schema description coverage this is a meaningful 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 names a specific verb/resource ('Pulls Form D / D-A filings live from EDGAR') and enumerates concrete outputs: a recency-weighted funding score, cadence hint categories, and buyer-profile-tuned action hints. This makes the tool easily distinguishable from sibling signal tools such as hiring_signal or compliance_signal.

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 when this tool is appropriate: it surfaces funding signals from the public, authoritative record of private securities offerings and adapts output by buyer profile. However, it does not explicitly name sibling alternatives or state when-not-to-use conditions, leaving some routing to inference.

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 that the operation is read-only, idempotent, and non-destructive, so the description does not need to restate that. It adds the useful detail that conversion uses the 'most recent reference rate' rather than a custom or historical rate, but it does not disclose output shape, rounding behavior, or rate-source limitations.

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 ('Convert an amount') and the key scope ('most recent reference rate'). There is no filler, redundancy, or irrelevant context.

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

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

For a simple three-parameter read-only conversion with rich annotations, the description is nearly complete: it states the action, the present-time scope, and the parameters are self-evident from the schema. The only missing piece is an explicit return-shape hint since there is no output schema, though the converted amount is strongly implied by the tool's purpose.

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 documents currency codes for from_currency and to_currency but leaves amount as just a number. The description does not fill that gap: it neither defines amount as a positive decimal in the source currency nor explains precision or minimums. It adds essentially no parameter meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Convert') and names the exact operation: an amount between two currencies, scoped to the most recent reference rate. This clearly distinguishes it from historical/timeseries fx siblings. An agent can identify what this tool does without opening sibling definitions.

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 'most recent reference rate' implies this is for current conversions rather than historical analysis. However, it never explicitly names alternatives such as fx_historical or fx_timeseries, nor does it state when not to use this tool. The agent must infer routing from sibling tool names.

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, so safety is covered. The description adds valuable behavioral context about the computation method (Pearson correlation of daily log-returns) and the banding logic, which goes beyond what annotations provide. It also specifies the base currency (USD), which is not in the schema. This enriches the agent's understanding without duplicating annotation data.

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, efficient and free of fluff. It front-loads the core function and then adds the output banding detail and use case. Every sentence contributes meaning, making it appropriately concise and 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?

The description explains the purpose and output banding, but lacks details on the exact output structure (e.g., which currency pairs) and the meaning of parameters like basket and horizon_days. Since there is no output schema, the description should compensate but does not fully. It is adequate for a simple read-only tool but leaves gaps for an agent to correctly set parameters and interpret results.

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 explain both parameters. The description mentions 'basket' but does not elaborate on its possible values (g10 vs majors) or their meaning. It completely omits the horizon_days parameter, leaving its role (lookback window) unclear. Without parameter descriptions in the schema or description, an agent cannot determine appropriate values or their impact on the output. The description adds no semantic value beyond the parameter names themselves.

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 computes 'Pearson correlation of daily log-returns vs USD across a basket' – a specific verb, resource, and scope. It also explains the output banding (strong_positive/positive/neutral/negative/strong_negative), making it distinct from other FX tools like fx_rates or fx_convert which focus on levels or conversions.

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 'Treasury/risk workflow for understanding multi-currency exposure' provides some context on when to use this tool, implying it is for correlation analysis rather than rate lookups. However, it does not explicitly contrast with sibling tools (e.g., fx_strength, fx_volatility_leaders) or state when not to use it. No alternative tool is named, leaving the agent to infer the differentiation.

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, open-world, non-destructive behavior. The description adds useful behavioral context—the complete list scope and the two specific fields returned—which compensates for the absence of an 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?

One concise sentence with no filler, front-loaded with the verb and scope. Every word adds value: 'every', 'reference-rate coverage', 'central bank', and 'peg classification' are all 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?

The tool is low-complexity (no params, safe read-only operation, no output schema). The description tells the agent what the response contains and the scope of the list, which is sufficient to select and invoke the tool correctly.

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

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

There are zero parameters, so there is nothing for the description to add over the input schema. The 0-param baseline of 4 applies; mentioning parameters would be redundant.

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

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

States a precise verb ('List') and resource ('every currency Ready APIs has reference-rate coverage for'), and names the output fields (issuing central bank, peg classification). This makes it easy to distinguish from sibling FX tools like fx_rates or fx_convert without needing their schemas.

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 communicates when to call it: when an agent needs the universe of currencies with reference-rate coverage, including central bank and peg details. It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops 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 safety profile is covered. The description adds that the tool returns a 'reference rate' for a past date, which is behaviorally consistent. It does not disclose potential edge cases like weekend/holiday rates, source, or rate timing, but given the strong annotation coverage, the added context meets the minimum 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 exactly two sentences with no redundant words. The purpose statement is front-loaded, and the example sentence adds practical value. Every part 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?

For a simple, read-only, 2-parameter tool, the description plus annotations cover the safety profile and give a concrete example. However, the base parameter remains unexplained, and with no output schema, the return value's shape is unknown. These are notable gaps for an agent trying 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 description coverage is only 50%: rate_date has a format example in the schema, but base has no schema description. The tool description's example 'USD→EUR' hints at currency pairing but does not explain the base parameter's meaning or how the quote currency is specified (there is no quote parameter). This leaves the base parameter ambiguous and fails to compensate for the schema 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 states the tool returns a 'reference rate for a specific past date' and gives a concrete example ('what was USD→EUR on 2024-11-15?'). This clearly conveys the action and resource. It implicitly distinguishes from siblings like fx_timeseries via the phrase 'specific past date', but it does not name the alternatives explicitly, so it falls just short of full sibling differentiation.

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

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

The description provides an explicit use case: answering single-date historical FX questions like 'what was USD→EUR on 2024-11-15?'. This gives clear context for when to use it. However, it does not state when not to use it or point to alternatives (e.g., fx_timeseries for ranges, fx_convert for current or forward conversions), so exclusions are missing.

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