DataNexus MCP

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

The description adds critical behavioral details beyond the annotations: the key is shown only once, must be stored immediately, must be passed as X-Api-Key, and rate limits of 3 keys per IP per 24 hours. This is exactly the kind of non-obvious behavior an agent needs to know.

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 primary action, then provides only high-value supporting details about key handling and rate limits. 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 single-parameter tool with an output schema and clear annotations, the description is complete: it explains what to do with the response, how to use the key subsequently, and the limitations that could affect agent behavior.

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

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

Schema coverage is 100% and the email parameter is already fully described in the input schema. The description essentially restates that email is required, adding 'delivery and repeat-signup lookup' context but no new mechanical detail.

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: generate a DataNexus API key for an email address. It clearly distinguishes this from the related sibling tools apikeys_revoke_api_key and apikeys_rotate_api_key by defining this as the creation operation.

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

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

The description gives clear context on when to use the tool: when a caller needs a new API key for an email address, and how the key should be used afterward. It does not explicitly exclude the rotate/revoke siblings, but the purpose is unmistakable.

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 destructiveHint=true, but the description adds valuable behavioral details: immediate revocation, irreversibility, and the need for human confirmation in automated pipelines. These specifics go beyond the annotation flags and help the agent understand the real-world impact.

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, with the warning front-loaded, followed by the action and consequences. Every sentence contributes essential information with no redundancy.

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

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

For a destructive tool with one parameter, the description fully covers purpose, consequences, and alternatives. An agent has everything needed to decide and invoke it correctly, especially with output schema available for return values.

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

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

The input schema already covers the single parameter 'key' with a clear description including format (dnx_...) and purpose. The description adds no further parameter information, but at 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'revoke' and the resource 'API key', making the action unmistakable. It explicitly says 'Permanently revoke' and differentiates from siblings like generate and rotate by emphasizing permanent removal.

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

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

The description provides clear context for when to use this tool, including the warning about human confirmation and irreversibility. It also suggests an alternative ('generate a new key') when access is needed again, though it doesn't explicitly mention the rotate sibling.

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 destructiveHint=true and readOnlyHint=false, and the description reinforces this with a clear warning. It adds value by noting the key is returned only once and should be stored immediately, and that it must be passed via a specific header. This goes beyond annotations.

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

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

The description is short, impactful, and front-loaded with the destructive warning. Every sentence adds value: the warning, the action, the one-time return, and the header note. No fluff.

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

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

For a destructive rotate operation, the description covers the core: what happens, the one-time return, and the header requirement. It doesn't specify the response schema (but an output schema exists) or explicitly mention that the old key becomes invalid, but that's implied by revoke. Given annotations and schema, this is adequately complete.

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

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

Schema coverage is 100% and the parameter description is self-explanatory. The tool description adds the tip about passing keys via the X-DataNexus-Key header, but this is more transport-level than parameter-level. Baseline 3 is appropriate since the schema already covers 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 action: 'Revoke the current API key and issue a replacement.' It specifies the resource (API key) and distinguishes from siblings like generate or revoke. The verb is explicit and the outcome is unambiguous.

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

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

The description warns it is destructive and requires human confirmation, which is crucial for safety. It implies it should be used when you need to replace an existing key, but doesn't explicitly contrast with generate or revoke. Siblings are available but not named as alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, and the description adds complementary behavior details: 'No side effects', 'US only', fuzzy name matching caveat, '24-hour cache', and verified source. It also discloses what the return contains, going well 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?

Although the description is long, every sentence contributes distinct information: purpose, safety, format, caveats, use-case, alternative routing, source/cache, and feedback fallback. It is front-loaded with the core purpose, and no sentence is redundant with the schema or annotations.

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 compliance check with existing output schema and comprehensive annotations, the description covers all operational needs: input format, fuzzy matching caveat, use case, alternative tool, data freshness, and what to do if the response is inadequate. Nothing essential 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 100%, so baseline is 3. The description adds meaningful value by specifying format ('9-digit EIN with or without dash'), providing an example ('Acme Corp or 13-1234567'), and warning that name match is fuzzy and EIN should be used for exact results. This exceeds the schema's basic 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?

States a specific verb ('Check') and resource ('US federal exclusions list'), clarifying it checks debarment status. It also explicitly distinguishes itself from the sibling tool govcon_search_contract_awards, telling the agent what this tool is not for.

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

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

Explicitly states when to use ('before awarding federal contracts or grants') and names the alternative for a different need ('Use govcon_search_contract_awards instead to find what contracts an entity has won'). This is clear, actionable 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?

The description repeats the annotation statements (Read-only, no side effects, idempotent), which is redundant but consistent, so no contradiction. It adds valuable context beyond annotations: 'US only', '24-hour cache', and 'Verified source: FINRA BrokerCheck'. This additional information about data freshness and provenance goes beyond what annotations provide, although it doesn't detail response format or error behavior. Given annotations already cover the safety profile, the description adds meaningful context, earning a 4.

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

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

The description is somewhat long but densely packed with necessary information. It front-loads the purpose and then covers parameters, usage guidance, alternative, source, cache, and a feedback fallback. While the repeated safety statements ('Read-only. No side effects. Idempotent.') are redundant given annotations, they don't waste much. The structure is logical and each segment serves a purpose, so it ranks above average but not perfect due to slight repetition.

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

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

Given the tool has an output schema (though not shown) and annotations cover the safety profile, the description provides everything needed for correct invocation: the primary input, its format, limitations (US only, no name lookup), alternatives, source verification, cache behavior, and a fallback mechanism via report_feedback. This is comprehensive for a simple one-parameter tool with rich structured metadata.

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?

Although the schema description provides the parameter name and a basic description, the tool description offers substantial added meaning: it specifies that the CRD number must be 'a string of digits', provides an example ('1234567'), states it is required, and clarifies that only CRD lookup is supported (not name lookup). This is significant semantic enrichment beyond the schema, which only states the format requirement. Since schema coverage is 100% but description goes further, it earns 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 clearly states the action ('Fetch'), the resource ('FINRA BrokerCheck registration'), and the specific scope (US brokers or investment advisers by CRD number). It distinguishes from sibling tools by explicitly stating it is not for healthcare providers and points to an alternative. The purpose is unambiguous and 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?

The description provides explicit when-to-use guidance: 'Use this when you have the CRD number' and explicitly names the alternative for healthcare providers ('Use compliance_search_npi_by_name instead'). It also states that name lookup is not supported, preventing misuse. This clearly guides the agent on when to select this tool over siblings.

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

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

Annotations already cover readOnly, idempotent, and non-destructive safety. The description adds beyond that: 24-hour cache (freshness), verified source (NPPES NPI Registry/CMS), US-only scope, and a concise summary of returned fields (name, credential type, taxonomy, address, status). This is meaningful operational context that annotations alone do not provide. 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 logically ordered: purpose, safety/geographic constraints, parameter details, return summary, usage guidance, source/cache, and feedback fallback. Purpose is front-loaded. Some redundancy with annotations ('Read-only. No side effects. Idempotent.') and schema is present, but each section earns its place and the text remains focused.

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?

Complete for a single-parameter read-only tool with an output schema: it covers provenance (NPPES/CMS), data freshness (24-hour cache), return-value summary, sibling routing, and the agent-gap feedback contract. An agent has everything needed to select, invoke, and interpret this tool correctly.

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

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

Schema description coverage is 100% and already documents '10-digit NPI number e.g. 1003000126. No dashes. Required.' The description mostly repeats this, adding only 'or spaces' to the formatting constraint. This is marginal added value, so a baseline 3 is appropriate — the schema carries the semantic weight.

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: 'Fetch NPI registration details for a US healthcare provider by NPI number.' Explicitly differentiates from the sibling compliance_search_npi_by_name by input type (exact NPI vs. provider name) and from other compliance fetch tools like compliance_fetch_finra_broker by the resource domain. An agent can immediately tell what this tool does and what it does not do.

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

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

Provides clear when-to-use guidance: 'Use this when you have the exact 10-digit NPI.' Names the alternative explicitly: 'Use compliance_search_npi_by_name instead when you only have the provider name.' Also adds a geographic constraint (US only) and a fallback instruction (report_feedback) for when the result doesn't serve the user's need.

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, and the description adds substantial behavioral context beyond them: geographic scope ('US only'), result limits ('Returns up to 10 matches'), data provenance ('Verified source: NPPES NPI Registry (CMS)'), freshness ('24-hour cache'), and the feedback loop behavior. The 'Read-only. No side effects. Idempotent.' phrasing is consistent with annotations; no contradiction.

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

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

The description is long but every clause earns its place: purpose, safety traits, scope, limits, parameters, return shape, alternatives, source, cache, and fallback. It is front-loaded with the core purpose. A minor deduction for being a single dense run-on paragraph and for partially repeating annotation facts ('Read-only. No side effects. Idempotent.'), though repetition is defensible since descriptions are not always shown alongside annotations.

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?

An output schema exists, so return values are covered structurally. The description supplies everything else an agent needs to call it correctly: parameter requirements and defaults, geographic and result-limit constraints, data recency, source authority, the sibling alternative, and the report_feedback fallback for failure cases. Nothing material is missing for a search tool of this 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?

Schema description coverage is 100%, so baseline 3 applies. The description largely restates the schema's parameter text (name, state, speciality) with the same examples (CA, Cardiology), adding only light value by mapping parameters to the return fields. It does not introduce meaningfully new parameter semantics beyond what the schema already documents.

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: 'Search the NPPES NPI Registry by provider name with optional state and speciality filters.' It also names the return fields and the sibling it is not ('Use compliance_fetch_npi_provider instead when you have the exact 10-digit NPI'), so an agent can distinguish this search-by-name tool from the fetch-by-NPI tool 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 states when to use this tool ('Use this when you do not have the NPI number') and names the alternative with its trigger condition ('Use compliance_fetch_npi_provider instead when you have the exact 10-digit NPI'). It also prescribes a fallback behavior via report_feedback with concrete arguments, leaving nothing 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?

With annotations indicating read-only, idempotent, and non-destructive, the description adds value by explaining the scoring methodology in detail (e.g., SPF score mapping, DMARC policies, DKIM selectors). It also notes the live DNS check via Cloudflare DoH with no cache, which is useful behavioral context beyond the annotations.

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

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

The description is highly detailed and well-structured, using bullet points for scoring criteria and a clear example. It is longer than a one-liner but every sentence adds value, explaining return fields and scoring rules. It is verbose but appropriate for the tool's complexity.

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

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

Given the complex scoring logic and the presence of an output schema, the description comprehensively explains the domains, scoring criteria, return fields, and example usage. An agent can accurately call the tool and interpret results without needing additional external documentation.

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 covers the domain parameter fully with description and format examples. The tool description reiterates the parameter format but doesn't add significant new semantics beyond what the schema already provides. Since coverage is 100%, a 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 explicitly states the tool checks SPF, DMARC, and DKIM email authentication for a domain, which is a specific verb and resource. It clearly distinguishes itself from sibling tools like domain_fetch_dns_records by focusing on security scoring 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 includes a clear example of usage and specifies the domain format. It doesn't explicitly mention when not to use it or list alternatives, but given the domain-specific nature and the example, it provides sufficient context for an agent to know when to invoke 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 cover readOnly, openWorld, idempotent, and non-destructive. The description adds useful context: 'No side effects', 'Returns all matching records currently in effect', '4-hour cache', and 'Verified source: Cloudflare DoH'. These details go beyond the annotations and help the agent understand caching and data freshness, so a 4 is warranted.

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 informative and front-loaded with the core purpose, but it is somewhat verbose, including a long feedback instruction block at the end. That block is useful but could be seen as auxiliary. Overall, it is organized with parameter labels and a clear usage note, so a 4 is fair.

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

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

The description covers the essential call context: source, caching, return behavior, and an alternative tool. There is an output schema present, so return structure need not be described. The only notable gap is the `record_types` required contradiction, which could cause misuse. But for a read-only tool with rich annotations and a schema, the description is otherwise complete.

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

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

Schema coverage is 100% for both parameters, so the description's parameter restatements add little. However, the description states 'record_types: ... Required.' while the input schema clearly marks it as optional with a default (required is only `domain`). This is a direct contradiction that misleads the agent into thinking `record_types` is mandatory. Although the description does list valid values and an example, the incorrect 'Required' label outweighs that benefit, making 2 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 starts with 'Fetch current DNS records for a domain via Cloudflare DNS over HTTPS', clearly stating the verb, resource, and source. It differentiates from the sibling `domain_fetch_domain_rdap` by explicitly naming it as the alternative for registration metadata, making the tool's scope unambiguous.

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

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

The description provides explicit guidance: 'Use this when you need live DNS resolution. Use domain_fetch_domain_rdap instead when you need registration metadata not DNS records.' This directly tells the agent when to use this tool versus the sibling, covering both inclusion and 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 cover readOnly, idempotent, non-destructive behavior, so the description doesn't need to restate those. It adds valuable context beyond the annotations: the crt.sh source, 4-hour cache, output ordering, and exactly which certificate fields are returned (issuer, validity dates, SANs). Minor gap: no mention of rate limits or failure 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?

The description is front-loaded with the core purpose, then layered logically: safety, parameter, return format, use cases, alternative, source, cache, and fallback. It is longer than necessary because of the boilerplate report_feedback block, but each component serves a real decision-making 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 tool with rich annotations and an output schema, the description covers everything needed to invoke it correctly: exact input format, return content and ordering, data source freshness, use cases, and the sibling alternative. Nothing relevant 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 100%, so the schema already fully documents the domain parameter, including the 'without protocol' example and required status. The description repeats the same information without adding substantive new semantics, so it sits at the baseline rather than exceeding it.

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

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

The description uses a specific verb-resource pair ('Fetch historical SSL certificate issuance') and identifies the data source (Certificate Transparency logs). It clearly distinguishes this from the sibling domain_fetch_ssl_certificate_chain by contrasting 'historical' with 'current certificate chain'.

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

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

The description gives explicit use cases: detecting domain hijacking or auditing unexpected historical issuance. It also names the exact alternative (domain_fetch_ssl_certificate_chain) and the condition for choosing it instead, plus a feedback fallback if the tool doesn't satisfy the user's need.

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 annotations (readOnly, openWorld, idempotent, non-destructive), the description adds concrete behavioral details: 'Verified source: IANA RDAP. 4-hour cache,' and 'registrant info where publicly available,' which warns about variable data availability. It also specifies the return payload fields and provides a feedback fallback mechanism. This is exactly the kind of contextual behavior an agent needs that annotations alone do not convey.

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 appropriately front-loaded: purpose first, then usage routing, then behavioral details, then feedback boilerplate. It stays readable despite the long fallback sentence, but 'Read-only. No side effects. Idempotent.' partially duplicates annotations, and the feedback block adds length. Still, every section serves a functional purpose 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 single-parameter read-only tool with an output schema, the description is complete: it explains the source, cache behavior, return fields, public-data caveat, and when to use alternatives. It also tells the agent how to escalate if the response is inadequate. Nothing essential for correct invocation 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 fully documents the single 'domain' parameter with 100% coverage, so the baseline is 3. The description repeats the same format guidance ('domain: Domain name without protocol e.g. example.com not https://example.com'), adding no meaning beyond the schema. It correctly emphasizes the required format, but does not elevate the parameter understanding.

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

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

The description opens with a specific verb and resource: 'Fetch domain registration details via IANA RDAP (the modern structured replacement for WHOIS).' It names the exact data returned (registrar, dates, nameservers, registrant info) and explicitly distinguishes itself from domain_fetch_ssl_certificate_chain and domain_fetch_dns_records. An agent can immediately tell what this tool does and what it is not.

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

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

The description gives explicit routing guidance: 'Use this when you need registration metadata. Use domain_fetch_ssl_certificate_chain instead when you need certificate history. Use domain_fetch_dns_records instead when you need live DNS resolution.' This names both the condition to select this tool and the alternative tools with their conditions, leaving no inference to the agent.

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 read-only and idempotent annotations, it discloses important runtime behavior: domain inputs are resolved to IPv4 A records, IPv6-only domains are unsupported, results are cached for 24 hours, and a daily quota of 100 calls applies. This is substantive context that neither the annotations nor the schema 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 front-loaded with the core purpose and remains information-dense; quota, source, cache, and fallback instructions all earn their place. It is slightly repetitive by restating read-only/idempotent traits already present in annotations, but this is minor.

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 a single parameter, an output schema, and full annotation coverage, the description fills the remaining gaps: accepted input formats, unsupported IPv6-only cases, API source, caching, quota, and an explicit fallback to report_feedback. Nothing needed to invoke it correctly 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 documents the single parameter well, but the description adds the A-record resolution rule and the IPv6-only exclusion, which are not in the schema. That added nuance justifies a score above the coverage baseline, though the core parameter meaning is largely restated.

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 opening sentence states a specific verb and resource: 'Find domains co-hosted on the same IP address (reverse IP lookup).' This unambiguously identifies the tool's output and clearly distinguishes it from siblings like domain_fetch_dns_records and domain_fetch_subdomains.

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 ('identifying shared hosting risk and mapping corporate infrastructure') and clearly defines the accepted input forms. It does not explicitly name alternative tools or state when not to use this one, 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, and destructiveHint false. The description adds valuable context beyond those: verified source (crt.sh), 4-hour caching, unsupported input types, and a fallback feedback path. This gives the agent a concrete behavioral model rather than merely restating the annotations.

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

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

The description is front-loaded with the core purpose and key safety traits, then layers limitations, use case, alternative, source, cache, and feedback instructions. It is longer than minimal, but every sentence adds decision-relevant information; the feedback boilerplate is the only slightly repetitive part.

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 with an output schema, the description is complete: it specifies inputs, limitations, return contents, source, cache behavior, when to use it, and when to use a sibling. Nothing an agent needs to call or interpret this tool correctly 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 documents the domain parameter with 100% coverage, so the baseline is 3. The description adds extra semantic constraints beyond the schema: 'Does not support IP addresses or wildcard domains' and reiterates the no-protocol format. This pushes it above baseline, though it does not need to do much more for a single-parameter tool.

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

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

The description starts with a specific verb and resource: 'Fetch SSL certificate history for a domain from Certificate Transparency logs.' It also enumerates the returned data (issuer, subject, validity period, Subject Alternative Names), making the tool's function unambiguous and distinct from siblings like RDAP or DNS lookup tools.

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

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

It explicitly states when to use the tool: 'Use this to detect unexpected certificate issuance or audit certificate history.' It also names the alternative: 'Use domain_fetch_domain_rdap instead when you need registration data not certificate data,' and clearly states unsupported inputs (IP addresses, wildcard domains).

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, and the description adds substantial operational detail: fallback source behavior, 24-hour caching with performance expectations, per-source timeout limits, circuit-breaker thresholds, and the source field in responses. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with purpose, but it has redundancy: the cache is mentioned twice, the source list is effectively repeated, and read-only/idempotent traits restate annotations. Useful content overall, but trimming duplicates would improve conciseness.

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

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

Covers primary and fallback sources, deduplication, cache behavior, response source field, timeouts, circuit breaker, and an explicit feedback fallback. An output schema exists for return structure, so nothing material 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?

Schema coverage is 100% and the schema already documents domain as required and protocol-free. The description repeats the same parameter information without adding new constraints, formats, or edge-case details, so it stays at the 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?

Description states a specific verb ('Enumerate'), resource ('subdomains for a domain'), and method ('via Certificate Transparency logs'). It also clarifies output as a deduplicated list, which distinguishes it clearly from sibling tools like domain_fetch_dns_records and domain_fetch_reverse_ip.

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 purpose is clear enough that an agent can infer when to use it (whenever subdomains are needed). However, there is no explicit when/when-not guidance or mention of alternatives such as domain_fetch_dns_records or domain_fetch_domain_history, so usage is only implied.

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 annotations (readOnlyHint, idempotentHint), the description adds crucial behavioral details: it explicitly notes that ${{ secrets.FOO }} and ${{ env.FOO }} references are NOT flagged, only literal secret values, and imposes a 500 KB limit. It also states 'Read-only. No side effects. Idempotent.' and includes a fallback feedback instruction, all consistent 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 dense but each sentence contributes necessary information: purpose, input method, parameter constraints, output, a critical behavioral caveat, and feedback routing. It is front-loaded with the primary purpose and avoids fluff, though it is longer than average due to the detailed behavioral and feedback notes.

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 two-parameter tool with an output schema, the description covers all essential aspects: what it does, how to provide input, parameter nuances, return structure (risk_level and findings), limitations, and a fallback path. Nothing an agent needs to invoke it correctly 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 100% for both parameters, so the baseline is 3. The description adds extra meaning for config_type: it specifies that vercel and netlify only get secrets checking in Sprint 8, while github_actions gets a full check suite. This nuance is not in the schema and helps the agent understand scope limitations.

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

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

The description clearly states the tool's purpose: scanning CI configs for exposed secrets, missing lockfile enforcement, and unpinned dependencies. It specifies the target resources (GitHub Actions, Vercel, Netlify) and the input method (paste content), distinguishing it from sibling tools like frontend_security_audit_manifest (which likely handles manifests) and frontend_security_detect_typosquatting.

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

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

The description clearly indicates when to use this tool (when you have CI config content to scan) and notes 'no filesystem access required', implying the content must be pasted. It does not explicitly name alternative tools or exclusion conditions, but the specific scope (CI configs) provides enough context 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, and destructiveHint=false. The description adds meaningful context beyond those: it specifies the data sources (OSV.dev, deps.dev, npm registry), the verdict thresholds (BLOCK/CAUTION criteria), and a feedback fallback (report_feedback with specific parameters). This goes well beyond what annotations alone convey, making behavior fully 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?

The description is long but densely informative. It is front-loaded with purpose and differentiator, then parameters, verdict criteria, sources, and feedback instructions. Every sentence serves a purpose, though it could be trimmed (e.g., repeating 'Read-only' and 'Idempotent' that annotations already state). Slight redundancy prevents a 5.

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 complete for a tool with 2 parameters, high schema coverage, and an output schema. It covers purpose, usage context, parameter semantics, verdict criteria, data sources, and a feedback path. Since the output schema exists, return format details are unnecessary. No critical information 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 100% with each parameter already documented, so the baseline is 3. The description adds value by explaining the consequence of providing vs omitting the lockfile (pinned versions vs semver ranges) and reinforces the 500 KB constraint. This exceeds the schema's basic descriptions, so a 4 is warranted.

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

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

The description states a specific verb ('Audit'), resource ('frontend package.json'), and outcome ('returns a single SHIP/CAUTION/BLOCK verdict with licence risks and abandonment signals'). It explicitly distinguishes from sibling security_fetch_package_vulnerabilities by scope (full manifest vs single package), so an agent can immediately identify when to use this tool.

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 contrasts this tool with security_fetch_package_vulnerabilities, stating this one takes the full package.json. It also explains the optional lockfile behavior (pinned vs semver ranges), giving clear context for when to include it. No explicit 'when not to use' beyond the differentiator, but that is sufficient given the specific alternative named.

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, but the description adds substantial behavioral context beyond those: it specifies the algorithm (Damerau-Levenshtein distance ≤ 2), the curated corpus, the false-positive reduction, and the exact return fields (is_likely_typosquat, closest_match, distance, risk_level). This is rich behavioral disclosure that goes beyond the structured 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, well-structured paragraph that front-loads purpose and usage, then covers parameters, algorithm, return fields, and fallback. It is somewhat long due to the detailed algorithm explanation and the report_feedback instruction, but every sentence contributes to the agent's understanding. It's not overly verbose; it earns its length.

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 two parameters and an output schema, the description covers all essential aspects: purpose, usage boundaries, algorithm details, return values, and the fallback feedback mechanism. An agent can correctly invoke it and interpret results without additional information. 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 provides 100% description coverage for both parameters (package_name and ecosystem) with clear descriptions and defaults. The description essentially restates the parameter information without adding new semantics. Baseline 3 is appropriate because the schema already does the heavy lifting; the description adds no extra 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 states the tool detects typosquatting, specifically optimized for the top 500 frontend packages, and explicitly contrasts with a full npm scan. It names the sibling security_detect_typosquatting for backend packages, making the distinction unambiguous. The purpose is concrete and actionable.

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

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

The description explicitly states when to use this tool (frontend packages) and when to use the alternative (backend packages, pointing to security_detect_typosquatting). It also provides the fallback instruction to report feedback if the tool doesn't serve the user's need. This is explicit guidance with clear alternatives and 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 readOnly, idempotent, and non-destructive behavior; the description adds useful context by naming sources (OSV.dev, deps.dev, npm registry), the wrapper relationship, and the returned signals. It repeats some annotation content but contributes beyond it.

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?

Purpose and usage are front-loaded and the structure is logical. It is slightly verbose due to repeating annotation facts and including a lengthy report_feedback fallback sentence, but every section serves a purpose.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining context: npm scope, sources, return fields, and the non-npm alternative. An agent has enough 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 coverage is 100%, but the description adds meaning by clarifying that package_name is an npm package name and that version is optional with latest resolved if omitted. This goes beyond the schema's basic examples.

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 it produces a SHIP/CAUTION/BLOCK risk brief for npm packages with frontend-specific context, and explicitly names the wrapped sibling security_fetch_package_risk_brief. This clearly distinguishes it from the general package risk tool.

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 instructs to use security_fetch_package_risk_brief for non-npm ecosystems, and frames this tool as npm-restricted with frontend-specific signals. It also provides a report_feedback fallback when the response does not serve the user's need.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description reinforces those but adds genuinely new behavioral context: a '4-hour cache' and a 'Verified source: SAM.gov + USASpending.gov,' plus the explicit feedback loop via report_feedback. These details go beyond the structured annotations and help an agent understand caching, provenance, and what to do on failure. No contradiction exists.

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

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

The description is relatively long but well-organized. It front-loads the core purpose, then covers safety, parameters, usage, and feedback in a logical order. Every sentence serves a purpose, including the encoding hint and the feedback fallback. It is not bloated; the length is justified by the added context. A minor deduction for not being more terse, but the structure is clean.

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

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

Given the tool's moderate complexity (3 params, output schema present, annotations present), the description is comprehensive. It covers purpose, usage, behavioral traits (cache, source), parameter details, output fields, and a feedback mechanism. Nothing an agent needs to call it correctly is missing. The output schema likely details the return shape, so the description's mention of specific fields is a bonus.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value with a specific encoding rule for the keyword parameter: 'Encode special characters — + becomes %2B.' It also lists the return fields, which, while not parameter semantics, give the agent an idea of what the output contains. This goes beyond the baseline of 3 for full schema coverage, earning a 4.

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

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

The description opens with a specific verb and resource: 'Fetch currently open government contract solicitations matching a keyword.' It clearly distinguishes itself from the sibling govcon_search_contract_awards by stating it is for open solicitations versus historical awards, and later explicitly names that alternative. This gives an agent a precise mental model of what the tool does and how it differs.

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

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

The description gives explicit usage instructions: 'Use this when looking for active bid opportunities. Use govcon_search_contract_awards instead when you need historical awards not open solicitations.' This clearly states when to use this tool and when to use a specific alternative, leaving no ambiguity. It also includes a fallback instruction to report feedback if the tool doesn't meet the need.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds useful context by disclosing fuzzy matching, a 4-hour cache, USASpending.gov as the verified source, and the categories of data returned. One small gap is that it does not clarify how a single US source relates to the EU and UK jurisdiction options.

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 economical, front-loading the core action and then adding safety, source, cache, output, and routing details. It is slightly long because it repeats some annotation facts, but no sentence is pure 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 an output schema present and only two simple parameters, the description covers everything needed for invocation: purpose, routing, source reliability, caching, matching behavior, and a feedback fallback. An agent can call this tool correctly without looking elsewhere.

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 schema already documents both parameters. The description adds meaningful behavioral detail by stating that fuzzy matching is applied to vendor_name, which helps the agent set expectations for imprecise company names.

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: Fetch the complete federal contract award history for a specific vendor. It also clearly distinguishes itself from govcon_search_contract_awards by framing this as vendor-specific lookup rather than topic exploration.

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 explicitly says to use this tool when researching a specific company's government contracting history and to use govcon_search_contract_awards instead for topic-area exploration. This gives an agent direct routing criteria and names the relevant 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful beyond-annotation context: 'Source: USASpending.gov + SAM.gov. 4-hour cache.' It also discloses return content (award amounts, recipient vendors, NAICS codes, award dates). No contradiction exists.

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

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

The description is appropriately sized and front-loaded with the core purpose. Each section (parameters, returns, alternatives, source, example) contributes useful information, though the inline parameter list slightly duplicates the input schema.

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 search tool with an output schema already present, the description is complete: it covers parameters, return fields, data source, cache behavior, when to choose alternatives, and provides a concrete example. Nothing an agent needs to invoke it correctly 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 100%, so the schema fully documents all four parameters. The description repeats the same parameter explanations with examples, but adds no new semantic meaning beyond what the input schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Search government contract awards by keyword, agency, and date range.' It clearly defines the tool's scope and later distinguishes it from sibling tools by noting it handles past awards, not active solicitations.

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

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

Explicit usage routing is provided: 'Use govcon_fetch_vendor_contract_history for all contracts by a specific vendor' and 'Use govcon_fetch_open_solicitations for active bids, not past awards.' This tells the agent exactly when to use this tool versus the relevant alternatives.

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

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

Beyond the annotations, the description discloses important behavioral details: fuzzy matching can return many results for common names, results are cached for 24 hours, and the data source is EPO OPS + USPTO. It also tells the agent what to do if the response does not serve the user's need. These are substantive, non-obvious traits that annotations do not 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 front-loaded with purpose and usage, then covers parameters, alternatives, source/cache details, and the feedback path. It is longer than strictly necessary because it repeats annotation flags like 'Read-only', 'No side effects', and 'Idempotent', but the structure is logical and every substantive section 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 two-parameter, read-only tool with a provided output schema and strong annotations, the description is complete. It covers input semantics, fuzzy-match behavior, source and caching, when to choose an alternative, and a fallback feedback procedure. No critical calling context 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 100%, so the schema already documents both parameters well; the baseline is therefore 3. The description adds useful examples ('Smith or John Smith', 'Apple Inc.') and a fuzzy-match warning for inventor_name, which goes slightly beyond the schema without being redundant or excessive.

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 ('Fetch') and a clear resource ('patent portfolio for a named inventor') with an optional assignee filter. It is immediately distinguishable from patent-retrieval siblings by anchoring on inventor rather than topic or patent number. The fuzzy-match caveat also clarifies what kind of result set to expect.

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 explicitly states when to use the tool ('when researching an inventor's work or a company's patent portfolio') and names the key alternative for topic-based needs: legal_search_patents_by_keyword. This gives an agent a concrete decision rule rather than leaving the choice 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 destructiveHint=false, so the description's restatement of 'Read-only. No side effects. Idempotent' adds no new safety info. However, it adds meaningful behavioral context not in annotations: automatic patent number normalization, a 24-hour cache, and the verified EPO OPS source. This goes beyond what structured fields convey, though it could have explained cache staleness or rate limits for an even higher score.

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

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

The description is relatively long, but every sentence earns its place: purpose, read-only assurance, parameter details, return fields, usage alternative, source/cache, and feedback escalation. It is front-loaded with the core action. The only mild redundancy is repeating read-only/idempotent which annotations already provide, but this does not significantly detract.

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 two-parameter tool with a full output schema and rich annotations, this description is remarkably complete. It covers exact input formatting, normalization behavior, a verified source, cache policy, return fields, and even a fallback feedback mechanism. No critical information an agent needs to call the tool correctly 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 100%, but the description adds substantial meaning beyond the schema: EPODOC format with concrete examples for EP, CN, JP, PCT, and US; the tropical interoperability of jurisdiction as a hint rather than a strict filter; and the auto-normalization behavior. This gives an agent the exact input format expectations and reduces the chance of malformed calls.

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-resource pair: 'Fetch full patent details by patent number and jurisdiction.' It differentiates from siblings by explicitly naming legal_search_patents_by_keyword for keyword-based searches, and from legal_fetch_patent_citations/legal_fetch_inventor_portfolio by its focus on a single patent's full details. Also lists concrete return contents, so an agent can identify the tool's scope immediately.

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 selection criteria: 'Use this when you have a specific patent number. Use legal_search_patents_by_keyword instead when you only have keywords and need to find patents.' It also explains the optional jurisdiction behavior, noting that passing a mismatched jurisdiction is still valid due to normalization, which prevents agent error. This is unambiguous when/not-when 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond those: 'Verified source: EPO OPS', '24-hour cache', automatic patent number normalization, and the citation direction 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?

The description is front-loaded with purpose and usage, then parameter details, source/cache info, and a feedback fallback. It is longer than minimal but each section earns its place; minor redundancy exists with annotations ('Read-only. No side effects. Idempotent.').

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 rich annotations, an output schema, and full schema coverage, the description covers all essential aspects: purpose, when to use, parameter formats, normalization behavior, source reliability, cache duration, and a fallback feedback mechanism. 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?

Although schema coverage is 100%, the description substantially enriches parameter understanding: it explains EPODOC format with concrete examples across EP, CN, JP, WO, and US, clarifies that jurisdiction is only an optional hint, and states that normalization makes mismatched jurisdiction valid.

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: 'Fetch forward and backward citation chains for a specific patent.' It clearly differentiates from the sibling legal_search_patents_by_keyword by stating the tool is for citation chains on a known patent, not topic search.

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

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

Explicit guidance is provided: 'Use this when building a prior art citation chain for a specific patent you already have. Use legal_search_patents_by_keyword instead when you need to find patents by topic not by citation.' This gives the agent a clear decision rule between alternatives.

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

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

Annotations already mark read-only/idempotent, and the description reaffirms them while adding non-structural details: 10-match cap, 24-hour cache, and verified data source. These details help an agent predict latency and freshness without contradicting 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?

Front-loaded with the core purpose and scoped to the point of use. It is dense but not bloated, though the feedback-instruction block at the end is long generic boilerplate that adds length.

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 search with an output schema, the description covers return content, result cap, cache behavior, source, and the fallback path if the result is inadequate. Nothing material 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 100%, so baseline is 3; the description goes beyond by giving inline examples for keywords, enumerating jurisdiction values with default, and specifying ISO 8601 format plus default behavior for date_from. This adds practical value over the schema alone.

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

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

States the action ('Search patents by keyword') with explicit resource and scope (EPO, USPTO, WIPO). The contrast with legal_fetch_patent_by_number removes any ambiguity about what this tool is for.

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 sets the condition for use: finding prior art or exploring a technology landscape without a specific number. It also names the alternative (legal_fetch_patent_by_number) for when a patent number is already known, and points to report_feedback for gap handling.

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, but the description adds valuable behavior beyond annotations: 'Verified source: UK Charity Commission OGL v3', '24-hour cache', and the returned fields (registration status, income, expenditure, activities, trustee count). It also discloses the feedback fallback behavior if results do not serve the user.

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 core description is front-loaded and efficient, with the main action, scope, and routing in the first two sentences. Slight deduction for the appended report_feedback boilerplate, which is long and not strictly needed for correct tool invocation, though it remains clearly separated.

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?

Coverage is complete for a tool with one parameter and rich annotations plus an output schema. The description adds jurisdiction, source trust, cache behavior, expected return contents, and explicit sibling routing. No important aspect of using the tool correctly 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 100% (baseline 3), but the description enriches the parameter with format details: 'UK registered charity number (7 digits, e.g. 1234567) or full/partial organisation name.' This is a meaningful addition beyond the schema's 'number e.g. 1089464 or name substring.'

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?

Opens with a specific verb-resource pair and scope: 'Fetch UK registered charity details by charity number or organisation name.' It clearly distinguishes itself from sibling tools by saying 'UK only' and naming the US alternatives, so an agent can route correctly 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?

Gives explicit when-to-use guidance: 'Use this for UK charities' and explicitly names alternatives ('Use nonprofit_fetch_nonprofit_by_ein or nonprofit_search_nonprofits_by_name for US nonprofits'). Also states 'UK only,' removing any ambiguity about jurisdiction.

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 annotations, the description adds meaningful behavioral context: 'No side effects. Idempotent. US only. 7-day cache. Verified source: IRS EO BMF + IRS TEOS.' It also discloses that it returns data from the most recent 990 filing. No contradictions with annotations.

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

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

The description is dense but not bloated. It front-loads purpose, then covers parameters, return fields, usage guidance, source, cache, and feedback fallback. The feedback sentence is long but contains actionable specifics, so it 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 one well-documented parameter, an output schema, and annotations covering safety, the description is complete. It adds return fields, source, cache behavior, usage guidance, and a fallback feedback path. Nothing needed for correct invocation 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 100%, so the baseline is 3. The description adds extra value by clarifying the EIN format: '9-digit Employer ID with or without dash, e.g. 46-5734087 or 465734087.' This goes beyond the schema's format example.

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: 'Fetch IRS 990 filing data for any US nonprofit by EIN.' It also names the sibling alternative (nonprofit_search_nonprofits_by_name) and clarifies this tool is for exact EIN lookups, making it easy to distinguish from related nonprofit 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?

Explicit usage guidance is provided: 'Use this when you have the exact EIN. Use nonprofit_search_nonprofits_by_name instead when you only have a name.' This clearly states when to use the tool and when to use 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?

The description discloses useful behavioral details beyond the readOnlyHint and idempotentHint annotations: it states the data source (IRS Form 990 via ProPublica), the rate limit (30/minute), that no auth is required, and the key return fields. This gives the agent a complete risk and execution picture for a read-only operation.

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

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

The description is well-organized and front-loads the core purpose before diving into output details and constraints. The report_feedback fallback adds length, but it is relevant operational guidance rather than filler. It remains concise enough for an agent to parse quickly.

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

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

The description covers the data type, source, output fields, parameter behavior, rate limits, authentication requirements, relationship to a sibling tool, and a fallback path via report_feedback. With an output schema also present, this description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with formats, defaults, and ranges. The description repeats the years default and range but adds no new semantic information beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's action: providing a 5-year financial trend for US nonprofits, with specific data categories and output fields. It distinguishes itself from the sibling nonprofit_fetch_nonprofit_full_profile by positioning this tool as the multi-year complement, so an agent can tell which tool to use.

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 connects this tool to nonprofit_fetch_nonprofit_full_profile and explains that it adds multi-year context, giving the agent a clear reason to select it. It does not fully enumerate when not to use it or provide alternative conditions for other nonprofit tools, but the context provided is sufficient for common use cases.

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

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

Discloses API source (ProPublica with IRS e-File fallback), refresh semantics, rate limit, no-auth requirement, and return fields, all beyond the read-only and idempotent annotations. It also provides a report_feedback fallback instruction if the response is insufficient. 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 front-loaded with purpose and key outputs, then adds API source, rate limit, auth, and feedback routing—each sentence adds operational value. It remains focused despite providing rich 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?

With one simple parameter, annotations, and an output schema, the description covers invocation context, expected return fields, source behavior, and failure fallback. An agent has enough to select and call the tool correctly without needing additional 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% and the only parameter, ein, is already fully explained with format and required status in the schema. The description adds no additional parameter-level meaning, 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?

Description states it performs complete nonprofit due diligence in one call, listing revenue trends, executive pay, risk flags, and a health score from IRS 990 data. This clearly distinguishes it from sibling tools like nonprofit_fetch_nonprofit_by_ein or nonprofit_fetch_nonprofit_financial_trends.

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 identifies target users (grant-makers, investors, compliance teams) and frames the tool as a one-call comprehensive due diligence option, giving clear context for when it fits. It does not explicitly name alternative sibling tools or state when not to use it, 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds material behavioral detail beyond that: max 25 results, the presence of revenue/assets/health scores with a 0–100 scale, acceptance of raw NTEE letters, the underlying ProPublica API, a 30/minute rate limit, and no-auth requirement. This fully discloses what the agent needs to know about side effects and constraints, with no contradiction.

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

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

The description is front-loaded with the core purpose and follows with essential details, then routing instructions. While it is longer than average, every sentence contributes: category mapping, rate limit, no-auth, and feedback fallback. No redundant fluff, though the feedback instruction could be condensed slightly. Overall it is well-organized and earns its length.

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

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

For a 2-parameter tool with a clear output schema (implied by the mention of revenue/assets/health scores) and read-only annotations, the description covers everything an agent needs: input constraints, response size, expected fields, rate limits, authentication status, and follow-up paths. Nothing critical 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?

Schema coverage is 100% (both params have descriptions), so baseline is 3. The description enriches the category parameter by enumerating all NTEE categories and noting that raw letters (A–Z) are also accepted, which is not in the schema. The state parameter is adequately defined in both schema and description. This adds value beyond the schema without fully compensating for the lack of enums (though enums are not present).

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, resource, and scope: 'Search US nonprofits by mission category and state.' It also lists the category choices and clarifies the return fields, making the tool's function unambiguous and distinct from sibling nonprofit_search_nonprofits_by_name, which searches by name instead.

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 positions this as a 'Starting point for nonprofit due diligence' and directs the agent to nonprofit_fetch_nonprofit_full_profile for deeper investigation. It also includes a conditional fallback to report_feedback with a detailed template, telling the agent when and how to escalate. This is explicit when-to-use and alternative 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. The description goes beyond these by stating 'US only', 'Returns up to 25 matches', 'Verified source: IRS EO BMF', '7-day cache', and includes a feedback mechanism. This adds valuable behavioral context without contradicting the annotations.

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

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

The description is a single paragraph but includes multiple pieces of necessary information: purpose, parameters, return fields, usage guidance, source, cache, and feedback. While it is somewhat long, each sentence contributes to the overall clarity. The key purpose is front-loaded, so it remains effective.

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

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

The description covers the tool's purpose, parameters, return fields, limits, data source, cache behavior, and a feedback fallback. With an output schema present, no additional return-value details are needed. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already describes both parameters. However, the description adds meaning by specifying that 'name' can be 'Full or partial organisation name' and that 'state' 'defaults to all states', which are not in the schema. This enhances understanding of 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 tool searches US nonprofits by name with an optional state filter, specifying the verb 'Search', the resource 'US nonprofits', and the scope 'by name'. It also explicitly distinguishes this from the sibling tool nonprofit_fetch_nonprofit_by_ein, making the purpose unambiguous.

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

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

The description gives explicit guidance on when to use this tool versus the alternative: 'Use this when you have a name but not the EIN. Use nonprofit_fetch_nonprofit_by_ein instead when you have the exact EIN for a precise single lookup.' This provides clear when/when-not 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 mark read-only, idempotent, and non-destructive. The description adds material behavior beyond annotations: 30-second timeout, slow large dockets, 4-hour cache, verified source with Federal Register fallback, and the exact return fields. No contradiction.

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?

Every sentence earns its place: purpose and safety first, then parameter, then usage routing, then performance/source/cache details, then the failure feedback path. Dense but structured and front-loaded.

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

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

For a one-parameter read-only fetch with an output schema, the description covers all operational context an agent needs: when to use, alternatives, timeout, cache, source verification, and how to report gaps. Nothing essential 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 documents docket_id with 100% coverage. The description supplements it with 'agency format' and two concrete example formats (EPA-HQ-OAR-2021-0317, FTC-2024-0041), which adds useful context but is only marginal 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 specific verb and resource: 'Fetch full details for a specific regulatory docket by ID.' It clearly distinguishes from the sibling search tool and focuses on retrieval by ID, so an agent can select it unambiguously.

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 usage context: 'Use this when you have a docket ID from a search' and directs to regulatory_search_open_rulemakings when topic discovery is needed first. It also scopes the tool to US federal dockets, covering prerequisites.

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, and the description repeats these. It adds context beyond annotations by specifying 'Verified source: Federal Register API', '4-hour cache', and default date-range behavior, which help an agent understand freshness and scope. 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 longer than average but densely informative: it front-loads the core purpose and safety traits, then covers parameters, usage, alternatives, and failure handling. Some duplication of schema content exists, but the added defaults and routing guidance justify the length.

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 output schema exists and annotations cover safety and idempotency, the description is complete for an agent to select and invoke the tool correctly. It covers what the tool returns, its source, cache behavior, defaults, the alternative tool, and a feedback fallback. Nothing essential 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 input schema already covers all parameters with descriptions and defaults (100% coverage), so the baseline is 3. The description adds meaningful extra semantics by stating 'defaults to last 90 days' for date_from and 'defaults to all notices' for keyword, which are not fully specified in the schema. It also repeats useful examples for each parameter.

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

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

The description opens with a specific verb and resource: 'Fetch recent Federal Register notices and rules for a specific agency.' It also immediately disambiguates scope with 'US federal only' and later names the sibling tool it is not ('regulatory_search_open_rulemakings'), so an agent can distinguish it from alternatives 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?

Explicit usage guidance is present: 'Use this to monitor recent regulatory activity for an agency' states when to call it, and 'Use regulatory_search_open_rulemakings instead when filtering by topic across all agencies' states the alternative condition. It also provides a fallback feedback path if the tool does not serve the user's need.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds genuinely useful behavior beyond annotations: 'US federal only' scope, '4-hour cache' freshness constraint, 'Verified source' provenance, and the report_feedback fallback instruction. The 'No side effects / Idempotent' phrases merely restate annotations and earn no credit, preventing a 5.

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?

Front-loaded with purpose, followed by behavior flags, parameter specs, and usage routing in logical order. Every section earns its place, but the trailing report_feedback boilerplate is verbose and template-like, adding length without much unique signal. Appropriately sized overall for a 3-parameter tool with API integration.

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 moderately complex search tool, nothing an agent needs to select and invoke it correctly is missing: purpose, scope, source, defaults, return fields, alternative routing, cache behavior, and failure fallback are all covered. Rich annotations and an existing output schema lower the burden on the description, which fully meets it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving richer examples for keyword ('artificial intelligence, data privacy'), an extra agency example (EPA), and explicit default behaviors ('defaults to all agencies', 'Default open'). This exceeds the baseline but stops short of 5 since the schema already documents each parameter adequately.

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 first sentence states a specific verb and resource: 'Search open rulemakings and public comment periods on Regulations.gov and the Federal Register.' It clearly differentiates from the sibling regulatory_fetch_docket_details by naming it explicitly and noting the condition that selects it (having a docket ID). The tool's scope (search vs. fetch) is 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?

Provides explicit when-to-use guidance ('Use this when monitoring regulatory activity on a topic') and names the exact alternative with its trigger condition ('Use regulatory_fetch_docket_details instead when you have a docket ID and need full detail'). This satisfies full when/when-not/alternative coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as persistence, rate limits, or response behavior, but it also does not contradict the annotations.

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

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

The description opens with a clear purpose sentence, then gives a compact parameter list and a helpful example. It is somewhat long due to eight parameters, but every line earns its place and there is no fluff.

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

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

With full schema coverage, an output schema, and annotations covering safety, the description is sufficient for an agent to invoke the tool correctly. The only missing piece is explicit sibling routing, which is a minor gap for a feedback tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats parameter names and constraints and adds an example call, but does not meaningfully extend beyond what the schema already documents.

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 opening sentence states a specific verb ('Report') and resource ('a data quality issue or agent intent gap for a DataNexus tool response'). This clearly distinguishes it from sibling tools like report_mcpize_link or validate_tool_output.

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

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

The description implies when to use the tool—whenever a data quality issue or agent intent gap exists—but gives no explicit guidance on alternatives or exclusions. The feedback_type parameter hints at one distinction, but that lives in the schema, not the description.

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

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

The description adds meaningful behavioral transparency by detailing the exact return structure (status, message, tool_id, and conditional upgrade_url) and including a usage example. Annotations already provide read-only, idempotent, non-destructive hints, so the description supplements rather than repeats them. It does not mention optional rate limits or error conditions, but for a simple status check this is acceptable.

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

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

The description is compact and well-structured: purpose, parameter clarification, return format, and an example. Every sentence contributes useful information, with no filler or redundancy. The purpose is front-loaded in the first line.

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 status check, the description covers the purpose, parameter, return shape, and example. The output schema (present) further enriches the context. It does not discuss error handling or unavailable tools, but those are minor given the simplicity of the tool and the presence of structured schema 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%, and the schema already documents the tool_id parameter with examples and usage instructions. The description duplicates this information and adds the return context, but it introduces no new parameter semantics beyond the schema. A 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 and resource: 'Check MCPize subscription status for a DataNexus tool.' This clearly distinguishes it from all sibling tools, none of which address MCPize status. The purpose is immediately understandable and precise.

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 to invoke: 'Pass the tool the user is asking about.' It implies the tool should be used when a user enquires about a specific DataNexus tool's MCPize subscription status. It does not explicitly mention alternatives, but no sibling covers this functionality, so no exclusion is needed.

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 useful context beyond that: it reduces context load, returns matching tool names and parameter hints, and should not be called recursively. It repeats the safety profile rather than contradicting it, and the added behavioral context is valuable.

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 every sentence earns its place: purpose, safety, usage timing, parameters, return content, exclusions, and fallback feedback path are all covered in a logical, front-loaded structure. Minor redundancy with annotations ('Read-only. No side effects.') does not hurt 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 two-parameter meta-tool with a rich annotation set and an output schema, the description is complete: it tells the agent when to invoke it, what it returns, when not to use it, and what to do if the result misses the user's need. Nothing necessary for correct invocation 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 100% and the description largely mirrors the schema: it explains query as a required plain-English task description with examples and domain as an optional filter with allowed sub-servers. This adds no meaning beyond the input schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Find the right DataNexus tool by describing your task in plain English.' It is clearly the tool-discovery entry point and explicitly differentiates itself from validate_tool_output and report_feedback, so an agent can distinguish it from 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?

Provides explicit when-to-use guidance ('Call this before any other DataNexus tool'), a concrete reason (reducing context load from 40000 to 800 tokens), and exclusions: 'Do not call this recursively or to validate results — use validate_tool_output for that.' It even specifies the fallback to report_feedback when the result is inadequate.

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 goes well beyond annotations by disclosing that the spdx_ids path uses a static table with no network call, the package path resolves from deps.dev with a max of 10 concurrent requests, there is a 50-item cap, a 60/minute rate limit, no auth required, and the output includes conflicting pairs with recommended actions.

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

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

The description is front-loaded with the core purpose and verdict, followed by implementation constraints, audience, and fallback instructions. Every sentence adds useful information, and the report_feedback sentence is standard but purposeful. No redundancy or filler.

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

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

With an output schema present, return values are already specified. The description covers input modes, output verdict, conflicting pairs, recommended action, network behavior, concurrency limits, item limits, rate limits, auth, target audience, and a feedback fallback. 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?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaningful context: packages use {name, ecosystem}, SPDX IDs bypass network calls, and there is a 50-item limit. It does not clarify whether both arrays can be supplied simultaneously, but this is a minor gap given the schema's optionality.

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 ('Audit') and resource ('licence compatibility of your entire dependency list'), and states the output verdict. It clearly distinguishes itself from single-package licence fetchers by emphasizing the entire dependency list and from policy-based audits by mentioning the static SPDX compatibility table.

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 identifies the intended audience and scenario: developers and compliance teams auditing open source licence risk before shipping. It also provides a fallback instruction to report_feedback when the tool doesn't serve the need. However, it does not explicitly mention when to prefer this tool over closely related siblings like security_audit_sbom_license_policy or security_fetch_licence_analysis.

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 annotations, the description adds substantial behavioral detail: OSV.dev as the vulnerability source, Redis persistence with 90-day TTL, input size limit of 500 KB, rate limit of 10/minute, no auth required, and action-specific return signals. This is exactly the kind of operational context that helps an agent predict side effects and constraints. The 'permanent' wording is slightly qualified by the TTL, but not contradictory.

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 and front-loaded with the core purpose, then proceeds through formats, persistence, limits, and use case. Most sentences earn their place. The final feedback-fallback sentence is boilerplate and not directly about the tool's behavior, which slightly reduces conciseness.

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

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

With an output schema present and full parameter coverage, the description goes beyond what is required. It includes operational constraints, supported formats, persistence details, authentication requirements, rate limits, and a clear use case. The only minor omission is explicit deregister semantics, but the action enum and output schema likely cover that.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying how the parameters interact with the action lifecycle: 'Returns go_no_go signal on register; new_findings on check' and 'sbom Required for register action.' This gives the agent more insight into how to use each parameter than the schema alone.

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

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

The description opens with 'Persistent SBOM watch' and immediately explains the lifecycle: 'Register once, check anytime for new CVEs affecting your dependency snapshot.' This clearly distinguishes it from one-shot vulnerability scanners like security_audit_sbom_vulnerabilities. It names the resource (SBOM watch), the actions, and the supported formats.

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: it is for DevSecOps teams monitoring production dependency exposure, and it emphasizes the persistent, repeated-use nature of the tool. However, it does not explicitly name an alternative for one-time SBOM scans or state when not to use this tool, so it stops short of full 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 declare readOnlyHint/idempotentHint, and the description adds substantial behavioral context beyond that: exact SPDX IDs only, no glob patterns, unlisted licences default to WARN, concrete default policy values, data source (deps.dev), and a 1-hour cache. It also discloses what the tool returns (verdict, blocked_packages, warned_packages, policy applied). 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 long but front-loaded with the core purpose, followed by parameters and behavioral constraints. Each sentence carries useful information, including the source/cache detail and the report_feedback fallback. The report_feedback sentence is somewhat generic and adds length, but it is actionable rather than filler.

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

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

Given the output schema exists and annotations cover the safety profile, the description supplies everything else an agent needs to invoke the tool correctly: input format, size limit, required vs optional parameters, policy semantics, defaults, output fields, source, and an explicit alternative for CVE audits. No critical selection or invocation information 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 100%, providing a baseline of 3, but the description adds significant meaning beyond the schema: concrete examples (GPL-3.0, MIT), explicit default behavior for block/warn/allow, the 'No glob patterns — exact SPDX IDs only' constraint, and the default WARN handling for unlisted licences. This is exactly the kind of policy detail an agent needs to construct a valid policy argument.

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 ('Audit'), a precise resource ('a CycloneDX or SPDX SBOM'), and a clear evaluation criterion ('against an SPDX licence policy') that returns a PASS/WARN/BLOCK verdict. It also distinguishes itself from a sibling by saying 'Use security_audit_sbom_vulnerabilities for CVE auditing instead.'

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 points to security_audit_sbom_vulnerabilities as the alternative for CVE auditing, and gives practical constraints for invocation: SBOM format, 500 KB max, policy structure, and default policy. It doesn't enumerate every related sibling (e.g., security_audit_licence_compatibility, security_audit_sbom_continuous), but the key routing guidance is present and unambiguous.

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

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

The description adds behavioral context beyond annotations, such as performance (up to 10 seconds for large SBOMs), return format (CVEs grouped by package with severity and fixed versions), source (Google OSV.dev batch API), and caching (1-hour). It also restates idempotency but annotations already cover that. No contradiction.

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 structured with front-loaded purpose and clear sections, but it repeats annotation facts (read-only, no side effects, idempotent) which are already available. Still, every sentence adds some value, so not excessively verbose.

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

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

Covers tool purpose, usage, behavior, performance, return output, alternative tool, and feedback instructions. With output schema present, it's complete for an agent to correctly invoke.

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

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

Schema coverage is 100%, and the description repeats the same parameter info without adding new semantics. Baseline 3 is appropriate.

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

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

The description clearly states 'Audit a Software Bill of Materials for known vulnerabilities across all listed packages' with a specific verb and resource. It also distinguishes from sibling 'security_fetch_package_vulnerabilities' by noting it's for a full SBOM, which sets it apart.

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

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

Provides explicit when-to-use: 'Use this when you have a full SBOM to audit' and when-not-to: 'Use security_fetch_package_vulnerabilities instead when checking a single package version.' Also notes performance for large SBOMs.

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 read-only/idempotent annotations, it discloses the Damerau-Levenshtein threshold, the top-10,000 comparison set, the returned verdict format, Redis-backed data, a cold-start penalty of ≤30s, the 60/minute rate limit, and that no auth is required. This is rich behavioral disclosure.

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?

Purpose and behavior are front-loaded in compact sentences. The addition of the rate limit, cold-start, auth, and feedback instructions make it longer than strictly necessary, but most sentences carry operational 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?

The description covers purpose, algorithm, outputs, performance, auth, and rate limiting, and an output schema exists. It is slightly incomplete for the cargo and go ecosystem values because it only mentions PyPI and npm download stats, leaving their behavior implicit.

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?

Both parameters are fully described in the input schema (100% coverage), including an enum for ecosystem, so the description does not need to repeat parameter details. The description adds algorithm context but no extra per-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 names a specific verb and resource: 'Detect typosquatting attacks against a package name', and adds the matching algorithm and output verdict. It is clear, though it does not explicitly differentiate itself from the closely named sibling frontend_security_detect_typosquatting.

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 a concrete use context: 'For security engineers auditing supply-chain package names before inclusion'. This communicates when the tool is appropriate, though it does not name alternatives or state when not to use it, 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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description reinforces these and adds useful context beyond them: the source is 'CISA KEV catalog (updated daily, cached)' and the result answers whether the CVE is actively exploited. This adds meaningful provenance and staleness context without contradicting annotations.

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

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

The first sentence is front-loaded and clear, followed by a logical flow: safety, parameter, return fields, source, alternative tools, fallback. Some redundancy exists—'Read-only. No side effects. Idempotent.' largely repeats annotations, and the report_feedback instruction is verbose—but the description is still well-organized and not bloated.

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

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

With only one parameter, an output schema, and comprehensive annotations, the description covers everything needed for correct invocation: exact parameter format, return fields, source and freshness, semantic interpretation, and routing to sibling tools. Nothing essential is missing for an agent to decide when and how to call this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying the exact CVE identifier format 'CVE-YYYY-NNNNN' with example 'CVE-2021-44228', and confirming it is required. This is more explicit than the schema's brief 'e.g. CVE-2021-44228' and helps prevent malformed invocations.

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 object: 'Check whether a CVE is in the CISA Known Exploited Vulnerabilities (KEV) catalog.' This clearly identifies the resource and the boolean nature of the query, and it distinguishes the tool from related CVEs tools by emphasizing KEV's unique role in answering active-exploitation triage.

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 routes to alternatives: 'Use security_fetch_cve_detail for full CVE severity. Use security_fetch_cve_epss for exploit probability.' It also states why KEV is the right choice (active exploitation question not available in NVD), and even provides a report_feedback fallback if the tool fails to satisfy the user.

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?

Although annotations already state read-only, idempotent, and non-destructive behavior, the description adds meaningful context: no side effects, verified NIST NVD source, 1-hour cache, and the specific fields returned. This goes beyond the structured annotations and helps an agent anticipate freshness and provenance.

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

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

The description is front-loaded with the core purpose, then covers usage rules, source, cache, and fallback behavior in a compact logical flow. Every sentence adds operational value, and the structure helps an agent scan it quickly.

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

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

For a single-parameter lookup tool with annotations and an output schema, the description is fully sufficient. It explains the return payload, provenance, caching, when to choose an alternative, and what to do if the result is inadequate. No critical context 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 input schema already documents cve_id with format and required status at 100% coverage. The description repeats the format and requirement but does not add substantial new meaning beyond what the schema provides. 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 states a precise verb and resource: 'Fetch full detail for a specific CVE by ID.' It also distinguishes itself from security_fetch_package_vulnerabilities by naming the sibling and clarifying the different query intent. An agent can clearly identify what this tool does and what it does not do.

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

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

The description gives explicit when-to-use guidance: use when you have a CVE ID and need complete detail beyond package-scan results, and use the sibling instead when you need all CVEs for a package version. It even provides a fallback action via report_feedback if the response does not satisfy the user's need.

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 readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond that: source (FIRST.org), 6-hour cache, and the exact return format (epss and percentile floats). No contradiction; it complements the annotations by explaining data freshness and scoring 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?

The description is well-structured with clear sections: purpose, parameter, returns, thresholds, usage guidance, source/cache, and an example. Each sentence contributes useful information and there is no fluff, though it is slightly longer than necessary.

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 annotations covering read-only and idempotent behavior, and an output schema present, the description supplies enough context for an agent: usage guidance, thresholds, source, and cache. It does not mention rate limits or error handling, but these are not critical for a simple read 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 covers 100% of the parameter, including a description and example. The description repeats the same example but adds little new meaning beyond what the schema already provides. As coverage is complete, baseline 3 is appropriate.

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

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

The description clearly states it retrieves the EPSS exploit probability score for a CVE, predicting likelihood of exploitation. It distinguishes itself from sibling security_fetch_cve_detail by noting that EPSS measures urgency while CVSS measures severity, making its purpose unambiguous.

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

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

It explicitly advises using this tool with security_fetch_cve_detail for prioritization and provides actionable thresholds (patch immediately >0.7, patch soon 0.3–0.7, monitor <0.3). This gives clear when-to-use and how-to-interpret guidance, including an alternative 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 indicate read-only and idempotent behavior. The description adds crucial details: UNKNOWN means all upstream sources were unreachable (not low risk), rate limit of 60/minute, no auth required, and that it makes a 'parallel call' to multiple sources. These go well beyond annotations and prevent misinterpretation.

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 longer than average but every sentence contributes: the verdict output, the UNKNOWN clarification, rate limit, auth, usage context, and fallback. It's front-loaded with the core purpose and then provides essential operational details. No fluff, though it could be slightly tightened.

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 that combines multiple sources and has an output schema, the description covers all necessary aspects: what it returns, how to interpret the UNKNOWN verdict, rate limit, auth, and when to use it. The presence of an output schema means return details don't need to be spelled out. Nothing essential 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 covers the sole parameter cve_id with a description and example, and schema coverage is 100%. The description doesn't add anything about the parameter itself beyond what the schema provides, which meets the baseline for high coverage.

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

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

The description states a specific verb ('fetch') and resource ('CVE risk summary'), explicitly lists the data sources (CVSS, CISA KEV, EPSS) and the exact verdicts returned. It clearly distinguishes itself from sibling tools that fetch individual data points like security_fetch_cve_detail or security_fetch_cve_epss.

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 explicitly says it is for security engineers triaging vulnerabilities 'after fetch_cve_watch fires', giving a clear context. It also includes a fallback instruction to call report_feedback if the result doesn't meet the need. However, it doesn't explicitly state when not to use it or name alternatives to avoid, but the context is strong.

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 annotations, the description adds rate limiting, no-auth requirements, Redis persistence, daily refresh sources, and the exact check response shape. This gives agents operational constraints and side-effect context not available in the structured annotations, and nothing contradicts destructiveHint.

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

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

The description is front-loaded with the core purpose and then provides operational details, rate limits, and response shape. The report_feedback fallback sentence is long but actionable; overall the description is dense without being padded enough to lose 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 full schema coverage, annotations, an output schema, and a description covering rate limit, auth, persistence, refresh cadence, and return shape, the tool is well specified. Minor omissions such as create-on-existing-watch_id behavior or handling of nonexistent watch IDs keep it from being 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 already cover all three parameters at 100%, so the schema does the heavy lifting. The description adds behavioral context such as 'on check' return fields, but it does not add per-parameter semantics like watch_id format or CVE ID validation beyond what the schema already states.

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

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

The description clearly identifies a persistent CVE watchlist with create/check lifecycle and specific event types. It is distinguishable from one-shot CVE lookup tools, but it does not explicitly contrast with the sibling security_fetch_cve_watch_status, so differentiation is implicit rather than explicit.

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

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

The description states the target user and workflow: security engineers tracking CVE exposure over time, creating once and checking anytime. It does not name alternatives or give when-not-to-use guidance, but the context is explicit enough to route most agents appropriately.

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 readOnlyHint and idempotentHint annotations, the description reveals crucial behavioral details: per-user cursor stored in Redis, first-call window, subsequent incremental returns, no external API calls, and instant response. It also provides a feedback fallback if results are insufficient, adding transparency about 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?

The description is fairly detailed but well-organized, starting with the core purpose, then efficiency note, parameter explanation, behavioral details, source, and feedback instruction. Some repetition of the parameter description exists, but each sentence contributes useful information without excessive padding.

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

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

The tool has an output schema, so return format is covered, and the description thoroughly addresses behavior, data source, performance characteristics, and error handling (feedback path). It is complete for a polling tool with stateful behavior, leaving no important aspect unexplored.

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

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

Schema coverage is 100% and the description reiterates the parameter's meaning, but crucially it adds that the IDs are the same as those used in security_fetch_cve_watch, providing essential context about where to obtain valid watch IDs. This adds value beyond the schema 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 clearly states the verb (check) and resource (CVE watches) and specifies it returns only watches with new events, distinguishing it from sibling creation tool security_fetch_cve_watch. It is specific and unambiguous.

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

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

It explicitly mentions running on a schedule and explains the behavior (first call returns last 30 days, subsequent calls only newer events), which guides when to use it. It does not mention alternatives explicitly but the linkage to security_fetch_cve_watch and the polling nature make context 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: the hard 8-second timeout with possible partial results, the 1-hour cache, and the verified source (deps.dev). These details help the agent anticipate edge cases and reliability. 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 informative but a bit long. It front-loads the purpose and key behavior, then covers parameters, usage, source, cache, and feedback. Each sentence serves a purpose, but the parameter repetition from the schema adds slight redundancy. Overall, it is well-structured and not excessively verbose.

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 complete for a read-only dependency tree tool. It covers the tool's purpose, behavior (timeout, cache, source), parameters (even if redundant), usage guidance, and even a fallback feedback mechanism if the result is inadequate. The presence of an output schema also covers return values. Nothing essential is missing for an agent to use 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?

The input schema already has 100% coverage with descriptions for all three required parameters (package, version, ecosystem), including examples and the ecosystem list. The description essentially repeats this information without adding new semantics. It mentions 'Exact version string e.g. 1.2.3' but the schema already has a similar example. Baseline 3 is appropriate since the schema carries the parameter 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 clearly states the tool's purpose: 'Fetch the full dependency tree for a package version including transitive dependencies.' It uses a specific verb (fetch) and resource (dependency tree), and explicitly distinguishes it from the sibling security_fetch_package_vulnerabilities, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use this to understand full supply chain exposure. Use security_fetch_package_vulnerabilities instead when you only need CVEs for a single package.' This clearly defines when to use this tool versus an alternative, and also mentions the timeout behavior for large trees.

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 annotations, the description adds concrete behavioral context: no network call for common licences, fallback API behavior, risk-level assumptions based on proprietary/commercial use, a 60/minute rate limit, and no auth requirement. This gives the agent an accurate operational model with no contradictions.

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

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

The description is compact and front-loaded: purpose, output summary, behavioral caveats, rate limit, auth, target audience, and fallback reporting instructions all appear without filler. Each sentence adds operational 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 tool with an output schema, the description covers inputs, outputs, network behavior, risk assumptions, rate limiting, auth, and intended users. An agent has sufficient information to select and invoke the tool correctly in context.

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

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

The schema fully documents spdx_id with examples (MIT, Apache-2.0, GPL-3.0) and marks it required, so parameter coverage is 100%. The description reinforces that the identifier can be any SPDX licence and mentions common vs rare identifiers, but adds no new parameter-level semantics beyond the schema.

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

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

The description clearly identifies the tool's resource and function: it analyses any SPDX licence identifier and returns obligations, permissions, limitations, risk level, and OSI/FSF status. It is distinct from package-oriented siblings like security_fetch_package_licence, though it does not explicitly name alternatives.

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

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

The description gives a specific use case: security engineers and developers understanding what a licence allows before including a dependency. It also explains operational behavior like the static top-50 bundle and fallback to spdx.org, but it does not state when not to use the tool or name sibling alternatives.

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

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

The description repeats the read-only/idempotent annotations but adds new facts: the verified data source (deps.dev, Google) and a 1-hour cache. These details give the agent practical expectations about freshness and provenance 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?

The description is well-organized: purpose first, then parameters, then use case, then provenance/cache, then fallback instructions. It is somewhat verbose and repeats annotation facts, but every section has a purpose and the key information is front-loaded.

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

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

For a read-only lookup tool with three required parameters, an output schema, and rich annotations, the description covers use case, alternatives, source, cache, and fallback behavior. It does not describe error handling for missing packages/versions, but that is a minor omission given the other structured data available.

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 gives examples for each parameter and emphasizes 'Exact version string' and requiredness, which the schema also documents at 100% coverage. However, the ecosystem list in the description (including RubyGems and capitalized names) differs from the list in the schema (lowercase, six ecosystems), creating ambiguity about acceptable values.

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-plus-resource statement: 'Fetch the SPDX licence identifier for an open source package version.' It names the sibling alternative (security_fetch_package_vulnerabilities) and clarifies the licence-focused use case, clearly distinguishing it from the many security tools in the sibling list.

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 explicitly states when to use the tool ('to verify licence compatibility before including a dependency') and when to use the alternative ('Use security_fetch_package_vulnerabilities instead when checking for security issues not licences'). It also provides an escalation path to report_feedback if the result is unsuitable.

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 and idempotentHint, and the description goes well beyond them. It discloses data sources, caching, rate limit (60/minute), no auth requirement, and the exact return fields including the anomaly_score range and maintainer_health values. This gives an agent a strong, accurate model of the tool's 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?

The description is dense but mostly purposeful: purpose, data source, cache behavior, return fields, rate limit, auth, and audience are all front-loaded. The trailing report_feedback fallback is boilerplate that adds noise, but the rest is efficiently structured and each technical detail 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 multiple output fields, external API dependencies, and rate limiting, the description is largely complete. It covers safety, data freshness, auth, and output semantics. The main gap is the unaddressed conflict between the stated npm/PyPI-only scope and the schema's cargo/go enum, plus the absence of explicit guidance for choosing between this and adjacent package security tools.

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. However, the description states 'npm or PyPI package' and 'Uses PyPI JSON API and npm registry', while the schema's ecosystem enum explicitly includes cargo and go. This contradiction can mislead an agent into rejecting valid inputs. The description adds no beneficial parameter meaning beyond the schema and introduces an erroneous restriction.

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 ('Analyse ownership and release history'), identifies the resource ('npm or PyPI package'), and states the intended outcome ('detect supply-chain risk'). It clearly distinguishes this from sibling tools like security_fetch_package_vulnerabilities and security_fetch_package_risk_brief by focusing on maintainer and ownership history rather than vulnerabilities or general risk.

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 explicitly names the target audience ('security engineers auditing open-source dependencies before inclusion in production builds') and the intended use case. However, it does not mention when not to use this tool or explicitly contrast it with closely related siblings such as security_fetch_package_risk_brief or security_fetch_package_vulnerabilities.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable context: data sources (OSV.dev, deps.dev, PyPI, npm), refresh policy ('data refreshed on each call'), rate limit (30/minute), and no-auth requirement. This goes beyond annotations and helps agents anticipate 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?

The description is dense but well-structured, front-loading the core verdict and then detailing return fields, constraints, and use case. The feedback instruction is extra but useful for agents. No redundancy, though it could be trimmed slightly without losing 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 an output schema present, the description does not need to explain return values but still lists them for clarity. It covers rate limit, auth, use case, and data refresh. It even provides a fallback (report_feedback) if the tool does not serve the user. No critical gaps for an agent to call it correctly.

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

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

Schema description coverage is 100% – all three parameters (package_name, ecosystem, version) have clear descriptions with examples. The description adds no new parameter-level meaning beyond what the schema already provides. Baseline 3 applies since the schema carries the load.

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

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

The description clearly states it provides a single SHIP/CAUTION/BLOCK verdict combining CVEs, licence, maintainer health, and transitive count. It distinguishes itself from more granular siblings like security_fetch_package_vulnerabilities by offering a consolidated risk brief. The verb 'fetch' and resource 'package risk brief' are specific and unambiguous.

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

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

It explicitly targets security engineers performing pre-inclusion package review, giving a clear context. However, it does not name specific alternatives or state when to prefer this over the granular tools (e.g., security_fetch_package_licence). The guidance is adequate but lacks explicit exclusions or comparisons.

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 annotations, the description discloses the 1-hour cache, the verified OSV.dev source, batch partial/failed_count semantics, and the fact that batch mode ignores package/version/ecosystem. This adds meaningful behavioral context without contradicting the read-only, idempotent 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 longer than average but well-organized, front-loading the core purpose and then structuring details by mode, return shape, and alternatives. Some phrases like 'Read-only. No side effects. Idempotent.' restate annotations, and the closing report_feedback boilerplate adds length without aiding tool selection.

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 dual-mode tool with five optional parameters and a rich result shape, the description covers mode selection, per-mode parameters, batch limits, return fields, data source, caching, and sibling tools. An agent has all essential information needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important semantics: mode-dependent precedence, the 50-item batch cap, and the package_name alias. It also gives concrete examples and includes RubyGems, which the schema's ecosystem property text does not list.

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 object: 'Fetch all known CVEs for an open source package version or a batch of packages.' It also explicitly names sibling tools for adjacent use cases, distinguishing this tool from security_fetch_cve_detail and security_audit_sbom_vulnerabilities.

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 defines single-package and batch modes and the condition that selects batch mode: a non-empty packages array. It also directs the agent to security_fetch_cve_detail for full CVE detail and security_audit_sbom_vulnerabilities for SBOM files, giving explicit 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses meaningful behavior: it is read-only and non-blocking, it runs deterministic rules before AI review, it returns pass or issues_found, and feedback is auto-filed only when both layers agree. This adds substantial context not available from the schema or annotations.

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

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

The description is front-loaded with the core purpose, safety, and behavior, followed by parameter context and clear usage guidance. It is somewhat lengthy and repeats some schema details, but every section serves a functional purpose and the structure makes it easy 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?

The description covers what the tool does, how it behaves, when to use it, when not to use it, what each parameter means and where to source it, and what to do if the output is unsatisfactory. With an output schema present, nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description mostly restates the schema's parameter meanings, with only minor additions like finding tool_id in any response and query_hash enabling feedback correlation. It meets the baseline but does not significantly extend 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 and resource: 'Validate a DataNexus tool response for data quality issues using two-layer validation.' It clearly distinguishes itself from report_feedback by contrasting validation with manual reporting, and the title reinforces the intent without circularity.

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

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

The description explicitly provides usage direction: 'Use validate_tool_output to check data quality. Use report_feedback instead to manually report an issue you have already identified.' It also gives a concrete fallback scenario with exact instructions, leaving no ambiguity about when to choose this tool versus its sibling.

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