DataNexus MCP

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

Beyond the annotations (all false), the description adds critical behavioral details: rate limit (3 keys per IP per 24 hours), the need to pass the key as X-Api-Key header, and a warning that the key is shown only once. This fully informs the agent.

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

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

The description is three sentences, each adding essential information: purpose, usage/limits, rate limit. No wordiness. Front-loaded with key action.

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

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

Given the simple nature of the tool (1 parameter, has output schema), the description covers generation, limits, key usage, and rate limiting. It is complete for the agent to select and invoke correctly.

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

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

The single parameter 'email' is described in the schema. The description adds that the email is 'used for delivery and repeat-signup lookup,' which provides context beyond the schema's basic description. Coverage is 100%, so baseline is 3; the added context justifies a 4.

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

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

The description clearly states 'Generate a DataNexus API key for the given email address,' which specifies the verb, resource, and context. This distinguishes it from sibling tools like revoke and rotate.

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

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

The description provides context on usage limits (10 free lookups/week for anonymous, 100/week for registered) and important storage instructions. However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

Annotations already indicate destructive and non-read-only behavior. The description adds value by detailing immediate effect and irreversibility, and explicitly warns about human confirmation. 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 extremely concise with three compact sentences plus a warning icon, front-loaded with the destructive alert. Every sentence provides essential information with no waste.

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

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

With one parameter and an output schema present, the description covers the core effect and safety warning. It could optionally mention error handling, but the output schema likely covers return values.

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

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

Schema coverage is 100% with a well-described parameter (key format dnx_...). The description does not add significant new meaning beyond the schema's description.

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

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

The description clearly states the tool permanently revokes an API key, using strong verbs like 'revoke' and 'stop working immediately'. It is distinct from siblings like generate and rotate.

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 warning about requiring human confirmation in automated pipelines, implying it should not be called unsupervised. It also suggests generating a new key if access is needed again, providing context about after-effects. However, it does not explicitly mention 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?

Reinforces annotations with clear warning ('DESTRUCTIVE') and adds critical behavior: 'store it immediately' and 'requires human confirmation'. No contradiction with annotations.

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

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

Two sentences, front-loaded with critical warning, no wasted words. Every sentence adds value.

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

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

Covers the essential: what it does, destructive warning, key storage instruction, and authentication method. Output schema exists, so return value info is adequate.

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

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

Schema coverage is 100% and the single parameter 'current_key' is well-described in the schema. The description adds minimal extra meaning beyond the schema, only noting key format and header.

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

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

Description clearly states 'Revoke the current API key and issue a replacement' with specific verb and resource. It distinguishes from sibling tools apikeys_generate_api_key and apikeys_revoke_api_key by combining both actions.

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

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

Explicitly warns about destructive nature and need for human confirmation. Mentions passing keys via header. Does not explicitly contrast with alternatives but the context of rotation vs. revoke/generate is 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?

Annotations declare readOnlyHint and idempotentHint; description confirms no side effects, idempotent, and adds US-only, 24-hour cache, fuzzy name matching, and return fields. Significantly supplements annotation context.

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

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

Description is dense and front-loaded with purpose. Each sentence provides essential information, though it could be slightly more concise. Still very efficient.

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

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

Given low complexity (1 param, annotations present, output schema implied), description covers all necessary context: return fields, caveats (fuzzy match, cache), and fallback instruction for reporting gaps.

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

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

Schema description coverage is 100%, but description adds examples (Acme Corp or 13-1234567) and clarifies fuzzy matching, adding value beyond schema's minimal description.

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

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

The description clearly states the tool checks if an entity is on the US federal exclusions list, using specific verbs and resources. It distinguishes itself from sibling tool 'govcon_search_contract_awards' by mentioning the alternative.

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

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

Explicitly says to use before awarding federal contracts/grants, and to use 'govcon_search_contract_awards' instead for contract search. Provides clear when-to-use and when-not.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description reinforces these with 'Read-only. No side effects. Idempotent.' and adds further behavioral context such as 'US only', '24-hour cache', and 'Verified source: FINRA BrokerCheck.' There is 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 fairly long but well-structured and front-loaded with the main purpose. It includes necessary details but could be slightly more concise. However, the organization is clear and every sentence adds value, so it earns a 4.

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, the description appropriately summarizes return values ('Returns registration status, qualifications, disclosure history, and employment history'). It covers all necessary aspects: purpose, limitations (no name lookup), source, caching, and fallback. For a simple one-parameter tool, this is complete.

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

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

The schema has 100% coverage for the single parameter crd_number, so baseline is 3. The description adds value by explaining what a CRD number is ('Central Registration Depository number as a string of digits e.g. 1234567'), reinforcing that it's required, and clarifying that name lookup is not supported. This extra context justifies a higher score.

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

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

The description clearly states 'Fetch FINRA BrokerCheck registration for a US broker or investment adviser by CRD number.' It uses a specific verb (fetch) and resource (FINRA BrokerCheck registration), and distinguishes itself from sibling tools like compliance_search_npi_by_name by specifying it's for financial advisers, not healthcare providers.

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 when you have the CRD number.' It also states when not to use it ('name lookup is not supported') and directs users to an alternative tool for healthcare providers. Additionally, it includes a fallback instruction to report feedback if the tool doesn't serve 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'Read-only. No side effects. Idempotent. US only.', plus a 24-hour cache and verified source, providing extra context 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 well-structured and front-loaded with purpose and usage guidelines. Every sentence provides value, though the feedback instruction at the end is a bit verbose but still useful. No redundant information.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers purpose, behavioral traits, parameter guidance, alternative tool, source, cache, and fallback feedback. It is complete and leaves no gaps for an AI agent.

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

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

The schema already has 100% coverage with description for npi_number. The description adds an example and clarifies 'Do not include dashes or spaces', which adds slight value beyond the schema.

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

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

The description clearly states the action ('Fetch'), resource ('NPI registration details'), and scope ('for a US healthcare provider by NPI number'). It distinguishes from the sibling tool compliance_search_npi_by_name, which is used when only the provider name is available.

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 ('when you have the exact 10-digit NPI') and when not to (use compliance_search_npi_by_name for name-based queries). Also provides formatting rules (no dashes/spaces) and indicates the parameter is required.

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?

Description adds 'Read-only', 'No side effects', 'Idempotent', 'US only', 'Returns up to 10 matches', return fields, source (NPPES NPI Registry), and 24-hour cache. All consistent with annotations which already indicate read-only, open-world, idempotent, and non-destructive.

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

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

Concise and well-structured. Front-loaded with key action and filters, then safety, usage guidance, return details, source, caching, and a feedback fallback. No redundant sentences.

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

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

Comprehensive: describes purpose, filters, safety, return structure, source, caching, and includes a feedback mechanism for missing results. Fully sufficient for agent decision-making.

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 (name, state, speciality) with proper details. Description does not add significant new semantic information beyond what the schema 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?

Clearly states the tool searches the NPPES NPI Registry by provider name with optional filters. Distinguishes from sibling compliance_fetch_npi_provider by specifying when to use each.

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 guides when to use this tool (when NPI number not available) and when to use the alternative (when exact NPI known). Also notes optional state and specialty filters.

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 extensively elaborates on behavior beyond annotations: it uses live DNS via Cloudflare DoH with no cache, explains scoring details for SPF, DMARC, DKIM, and describes parallel checking of 10 selectors. This gives full transparency on how results are derived.

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

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

The description is well-structured with a front-loaded purpose, followed by parameter and return format, then detailed scoring explanations. Every sentence adds value, and it is appropriately sized for the complexity.

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

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

Given the tool has an output schema, the description complements it by explaining the scoring logic and DNS source. It covers all necessary aspects for an agent to invoke the tool correctly and interpret results.

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

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

Schema description coverage is 100% and the description merely repeats the same information ('domain: Domain without protocol'). It adds no additional meaning beyond the 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?

The description clearly states the tool checks SPF, DMARC, and DKIM email authentication for a domain. It uses specific verbs ('Check') and resource ('domain's email authentication'), and effectively distinguishes from sibling tools like domain_fetch_dns_records by focusing on email security.

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

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

The description provides clear context for when to use the tool (to assess a domain's email security posture) but does not explicitly mention when not to use it or suggest alternatives. The focus is strong, but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description reinforces these but adds non-obvious behavior: 'Verified source: Cloudflare DoH. 4-hour cache' and 'Returns all matching records currently in effect.' This provides useful context beyond the structured annotations, though it does repeat some annotation content.

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

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

The description is dense and front-loaded with the core action, then adds parameter details, usage guidance, source, cache, and a feedback fallback. While it redundantly restates annotation hints ('Read-only. No side effects. Idempotent.'), the additional clauses earn their place by covering valid values, usage alternatives, and data freshness.

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

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

Given the rich annotations, output schema, and simple parameters, the description covers all necessary guidance: what it returns, when to use it, alternatives, valid inputs, and cache behavior. The only minor gap is potential error cases, but these are adequately handled by the output schema.

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

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

The schema's record_types property says 'Optional' while the required array includes it; the description resolves this by explicitly marking both domain and record_types as Required and enumerating the valid record types (A, AAAA, MX, TXT, NS, CNAME, SOA) with an example. This meaningfully adds value beyond the schema, which lacks enums and misstates 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 clear specific action: 'Fetch current DNS records for a domain via Cloudflare DNS over HTTPS.' It distinguishes this tool from sibling domain_fetch_domain_rdap by explicitly stating it's for DNS records, not registration metadata, leaving no ambiguity about the tool's role.

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 'Use this when you need live DNS resolution' and then directs to domain_fetch_domain_rdap for registration metadata. It also adds context about the source and cache (4-hour cache), helping the agent decide whether freshness is acceptable.

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 reiterates the annotations (readOnlyHint, idempotentHint) with 'Read-only. No side effects. Idempotent.' and adds additional context: '4-hour cache' and 'Verified source: crt.sh'. This adds value beyond the annotations.

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

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

The description is moderately long but each sentence adds value: purpose, idempotency, parameter format, use case, alternative, source, cache, and feedback instruction. It is front-loaded with the primary action. Could be slightly more concise but still efficient.

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

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

Given the presence of an output schema, the description does not need to detail return values. It covers purpose, usage guidelines, parameter semantics, behavioral traits, and even includes a feedback fallback. The tool is a simple read-only data fetch, and the description is fully sufficient.

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

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

The input schema already has 100% coverage with a clear description for the 'domain' parameter. The description repeats this information but does not add new meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Fetch'), resource ('historical SSL certificate issuance'), and source ('Certificate Transparency logs'). It also distinguishes from the sibling tool 'domain_fetch_ssl_certificate_chain' by specifying the use case for historical data versus current 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 provides explicit guidance on when to use this tool ('detect domain hijacking or audit unexpected historical certificate issuance') and explicitly names the alternative tool for current certificate needs ('domain_fetch_ssl_certificate_chain').

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description reinforces these ('Read-only. No side effects. Idempotent.') and adds cache duration (4-hour cache) and data source (IANA RDAP), providing useful context 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 well-structured with clear sections but contains some redundancy (e.g., repeating annotations). It is front-loaded with the primary purpose and remains concise overall.

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

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

Given the single parameter, strong annotations, explicit usage guidelines, output schema existence, and a fallback feedback instruction, the description is fully 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 coverage is 100% and the description repeats the parameter format ('domain without protocol'). It adds minor clarity ('not https://example.com') but does not significantly enhance the schema information.

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 fetches domain registration details via IANA RDAP and lists the returned fields (registrar, dates, nameservers, registrant info). It distinguishes from sibling tools like domain_fetch_ssl_certificate_chain and domain_fetch_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?

Explicitly states when to use ('when you need registration metadata') and provides alternatives for certificate history and DNS resolution. Also includes a feedback mechanism for cases where the response is insufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description reinforces these with 'Read-only. No side effects. Idempotent.' and adds extra behavioral info: daily quota, source (HackerTarget API), and 24-hour cache. 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 well-structured and front-loaded with the main purpose. It includes necessary details without redundancy. Every sentence adds value, covering purpose, constraints, use cases, quota, source, and fallback. It is slightly long but still concise for the information provided.

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 one required parameter, annotations, and an output schema (implied), the description covers all key aspects: purpose, input format, constraints, caching, quota, source, and a fallback mechanism. It is complete and leaves no obvious gaps for an AI agent to select and invoke 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?

The input schema has one parameter with a description. The description adds value by explaining that if a domain is given, it is first resolved to its IPv4 A record, and that IPv6-only domains are not supported. This goes beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: 'Find domains co-hosted on the same IP address (reverse IP lookup).' This is a specific verb ('find') and resource. It distinguishes well from sibling tools like domain_fetch_dns_records and domain_fetch_domain_history.

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

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

The description provides clear context for when to use the tool ('identifying shared hosting risk and mapping corporate infrastructure'). It also notes constraints (IPv6 not supported) and includes a fallback instruction to call report_feedback if needed. However, it does not explicitly state when not to use or compare with alternative tools.

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

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

Description reiterates annotations (read-only, no side effects, idempotent) and adds constraints like no IP/wildcard support, verified source (crt.sh), and 4-hour cache. 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?

Every sentence adds value; no fluff. Clear hierarchy: purpose, parameter, usage, alternative, fallback. Well-structured within a single paragraph.

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 purpose, parameter constraints, usage guidance, caching, source verification, return value summary, and fallback agent gap reporting. Output schema exists so return value description sufficient.

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

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

Schema has 100% coverage with one parameter described. Description adds constraint that domain must not include protocol and explicitly says 'Required.' plus 'Does not support IP addresses or wildcard domains,' which goes beyond schema.

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

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

Description clearly states verb 'Fetch' and resource 'SSL certificate history for a domain from Certificate Transparency logs'. It distinguishes from sibling tool 'domain_fetch_domain_rdap' by specifying when to use each.

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 ('detect unexpected certificate issuance or audit certificate history') and when not to use ('use domain_fetch_domain_rdap for registration data'). Also provides source and cache info.

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 detailing caching (24h cache, performance timelines), circuit breaker behavior, fallback sources, and the response source field. Annotations already declare readOnlyHint and idempotentHint, and the description reinforces these without 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 somewhat lengthy but justifiably so given the complex behavior (sources, caching, circuit breaker, feedback). It is well-structured: first sentence conveys the core purpose, followed by parameter details, source information, caching behavior, and error handling. Every sentence serves a purpose, though it could be slightly more concise.

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

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

Given the presence of an output schema (not shown), the description does not need to detail return values. It covers all essential aspects: purpose, parameters, sources, caching, circuit breaker, and feedback mechanism. No gaps are apparent for a subdomain enumeration 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?

There is only one parameter 'domain' with a schema description that covers its meaning and required state. The description repeats this information and provides an example. Since schema coverage is 100%, the description adds marginal value beyond the schema, earning a baseline score of 3.

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

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

The description clearly states the tool enumerates subdomains for a domain via Certificate Transparency logs. The verb 'enumerate' and resource 'subdomains' are specific. It distinguishes from sibling tools like domain_fetch_dns_records by focusing solely on 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 provides clear context on when to use this tool (to get subdomains) and includes details on sources, caching, and fallback behavior. It also directs users to call report_feedback if the response is insufficient. However, it does not explicitly state when not to use it or compare to alternatives, which is acceptable given the sibling list.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description reinforces 'Read-only. No side effects. Idempotent.' and adds important nuance: ${{ secrets.FOO }} and ${{ env.FOO }} are NOT flagged, only literal secrets. Also mentions 500 KB limit. Adds value beyond annotations.

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

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

Description is moderately sized but packs essential info. Front-loaded with main action and key details. A few sentences could be streamlined, but no unnecessary words. Well-structured.

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

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

Given tool complexity (multiple config types, output with risk_level and findings), description covers key behaviors, limitations, and output fields. Mentions the feedback mechanism for gaps. Has output schema, so return values are covered. Edge cases like not flagging template references are addressed.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: config is raw YAML/TOML content, config_type enumeration details (github_actions with full check suite, others secrets only in Sprint 8). Also notes 500 KB max and default value. This enriches the schema.

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

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

The description clearly states the tool scans CI configs for exposed secrets, missing lockfile enforcement, and unpinned dependencies, specifying supported platforms (GitHub Actions, Vercel, Netlify). This distinct verb-resource combination differentiates it from siblings like frontend_security_audit_manifest.

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 tells when to use: paste config content, no filesystem access. Provides a NOTE on what is not flagged and a fallback to report_feedback if the result doesn't serve. This includes exclusions and alternative actions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces these with 'Read-only. No side effects. Idempotent.' and adds detailed behavioral context: data sources (OSV.dev, deps.dev, npm registry), verdict criteria, and fallback. 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 well-structured and appropriately sized. It front-loads the purpose and distinction, then covers parameters, verdict criteria, sources, safety, and fallback. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (audits a full package.json, returns a verdict with multiple criteria, has optional lockfile), the description is complete. It covers purpose, parameters, criteria, data sources, side effects, and fallback. The output schema exists but is not needed for completeness as the verdict logic is described.

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

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

Schema description coverage is 100%, with both parameters described. The description adds meaningful detail: manifest is required with 500 KB max, lockfile is optional and affects whether pinned versions or semver ranges are audited. This goes beyond the schema's short descriptions.

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

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

The description clearly states the tool audits a frontend package.json for security risks, returning a SHIP/CAUTION/BLOCK verdict with licence risks and abandonment signals. It distinguishes itself from the sibling security_fetch_package_vulnerabilities by noting it takes the full package.json instead of a single package.

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 vs alternatives (e.g., different from security_fetch_package_vulnerabilities). Also provides guidance on optional lockfile parameter: audits pinned versions if provided, otherwise semver ranges. Includes a fallback instruction to report feedback if 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, idempotentHint, and destructiveHint. The description adds algorithmic detail (Damerau-Levenshtein distance ≤ 2) and return fields, confirming no side effects and idempotence. It does not contradict annotations.

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

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

The description is a single paragraph that efficiently covers purpose, differentiation, algorithm, return, behavior, and a feedback fallback. It is not overly verbose, though could be slightly more streamlined.

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

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

Given the simple tool with 2 parameters and high schema coverage, the description is complete: it explains purpose, usage, algorithm, output, behavior, and even includes error handling via feedback. Minor omission of error scenarios but overall sufficient.

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

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

Schema coverage is 100%, with both parameters described. The description reiterates the purpose of each parameter but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Typosquatting detection optimised for the top 500 frontend packages'. It lists exemplar packages and distinguishes itself from the sibling tool 'security_detect_typosquatting' by specifying it is for frontend packages and has fewer false positives.

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

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

The description explicitly says when to use: for frontend packages, and when not to: for backend packages use 'security_detect_typosquatting' instead. This provides clear guidance and 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 value by stating 'Read-only. No side effects. Idempotent.' and listing sources (OSV.dev, deps.dev, npm registry). It also explains the wrapping behavior. 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 comprehensive but not overly verbose; it front-loads the purpose and provides essential details. It loses a point for being slightly lengthy but remains well-structured and informative.

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

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

Given the output schema existence, annotations, and the description covering purpose, parameters, usage guidelines, behavioral traits, sources, and fallback behavior, the description is fully complete. It enables an agent to understand when to use, how to use, and what to expect.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning: package_name is described as 'npm package name. Required.' and version is described as 'Optional pinned version — latest resolved if omitted,' which clarifies behavior beyond the schema's 'Package version e.g. 2.28.0. Optional.'

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: providing a SHIP/CAUTION/BLOCK risk brief for npm packages with frontend-specific context, differentiating it from the wrapped security_fetch_package_risk_brief. It specifies the added signals (weekly_downloads, is_ui_component) and explicitly mentions it is restricted to npm.

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 tells when to use this tool (for npm packages) and when not to ('Use security_fetch_package_risk_brief for non-npm ecosystems'). It also provides a fallback mechanism: calling report_feedback if 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 read-only, idempotent, non-destructive. Description adds 'No side effects', 'Idempotent', cache behavior (4-hour), and data source, providing rich context 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 a single paragraph but covers all necessary aspects efficiently. Some repetition (e.g., 'Mandatory' in description of keyword) but overall well-structured and compact.

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 3 parameters, rich annotations, and output schema present, the description is fully complete: it explains purpose, usage, parameters, return fields, source, cache, and error feedback. No gaps.

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

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

Schema already has 100% coverage with descriptions. Description adds encoding guidance for keyword, default values for optional params, and explains expected date range behavior (implied from 'currently open').

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 fetches open solicitations with a keyword, and explicitly distinguishes it from the sibling tool for historical awards, 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?

Provides explicit when-to-use ('active bid opportunities') and when-not-to-use (use govcon_search_contract_awards for historical awards). Also includes fallback feedback mechanism.

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 reinforces these with 'Read-only. No side effects. Idempotent.' and adds further details: fuzzy matching, cache duration, verified source. 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 comprehensive but not overly verbose. It front-loads the core purpose and groups information logically (purpose, safety, parameters, usage, source, cache, fallback). A slightly tighter structure could remove redundancy, but 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?

Despite having an output schema (not shown), the description lists key return fields. It covers safety, parameters, usage, alternatives, source, cache, and even error handling via report_feedback. For a two-parameter tool with rich annotations, this is fully complete.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds value by noting 'Fuzzy match used' for vendor_name, which goes beyond the schema. With high baseline, the addition earns a score above 3.

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

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

The description states the tool fetches 'complete federal contract award history for a specific vendor' — a specific verb and resource. It distinguishes from the sibling tool 'govcon_search_contract_awards' by specifying when to use each, ensuring clear differentiation.

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

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

Explicitly tells when to use ('when researching a specific company's government contracting history') and when not to use ('use govcon_search_contract_awards instead when exploring a topic area without a specific vendor'). Provides clear context and alternatives.

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

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

Annotations indicate readOnly and non-destructive. Description adds cache duration (4 hours), data source (USASpending.gov + SAM.gov), and return fields. Some behavioral details like pagination or max results are missing.

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

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

Well-organized with a summary sentence, parameter list, return info, sibling guidance, and source details. No redundant text.

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

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

Given the rich annotations and output schema, the description covers purpose, parameters, return content, data source, caching, and comparisons to siblings. It is fully adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats parameter descriptions and adds an example, but does not introduce new 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?

Clearly states the tool searches government contract awards with keyword, agency, and date range filters. The example and sibling differentiations reinforce the specific verb and resource.

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 tells when to use alternatives: govcon_fetch_vendor_contract_history for vendor-specific queries and govcon_fetch_open_solicitations for active bids. This leaves no ambiguity.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds fuzzy match disclaimer, data source, cache duration, and expected result fields, which are valuable 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?

Description is relatively long but well-structured with clear sections (purpose, params, usage, source, feedback). Front-loads key info. Could tighten slightly but effective overall.

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

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

Covers all important aspects: fuzzy matching, result fields, data source, cache, alternative tool, feedback mechanism. No gaps given the tool's moderate complexity and presence of output schema.

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

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

Schema coverage is 100%. Description adds examples (e.g., inventor_name: 'Smith or John Smith'), clarifies fuzzy matching implications, and explains assignee optionality. Adds meaning beyond schema.

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

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

Clearly states it fetches patent portfolio for a named inventor with optional assignee filter. Distinguishes from sibling legal_search_patents_by_keyword by specifying topic vs. inventor focus.

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

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

Explicitly says when to use (researching inventor or company portfolio) and when not (use legal_search_patents_by_keyword for topics). Includes feedback mechanism for gaps.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds further context: 'Read-only. No side effects. Idempotent', '24-hour cache', 'Verified source: EPO OPS', and normalisation behavior. 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 ~150 words and well-structured: purpose, behavior, parameter details, return summary, usage contrast, source, caching, feedback. While slightly verbose, every sentence adds value and there is no redundancy. Could be trimmed slightly, but very 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?

Given the presence of an output schema (not detailed but listed fields), the description covers return values (title, abstract, etc.), parameter constraints, caching policy, and a fallback feedback mechanism. For a tool with 2 parameters and clear purpose, this is highly complete.

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

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

Schema description coverage is 100%, but the description adds significant value: explains EPODOC format, provides concrete examples for each jurisdiction, clarifies optionality and default of 'jurisdiction', and states that passing mismatched jurisdiction is valid due to normalisation.

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 what the tool does: fetch full patent details by patent number and jurisdiction. It uses a specific verb ('fetch') and resource ('patent details'), and explicitly distinguishes itself from the sibling tool 'legal_search_patents_by_keyword' by stating when to use each.

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 when you have a specific patent number. Use legal_search_patents_by_keyword instead when you only have keywords.' It also explains parameter behavior (automatic normalisation) and provides a feedback fallback mechanism.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds: 'Read-only. No side effects. Idempotent.' Also discloses normalization behavior, cache duration (24-hour), and data source (EPO OPS).

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 information-dense but slightly verbose with multiple examples and normalization explanation. However, it is well-structured with core purpose first, then parameter details, usage guidance, and fallback instructions.

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

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

Given the presence of an output schema, the description still explains return value structure: 'citing patents (forward citations) and cited patents (backward citations) with filing dates and titles.' Also covers error handling via report_feedback and data freshness.

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

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

With 100% schema coverage, description adds significant detail: EPODOC format examples for patent_number, default for jurisdiction, and normalization rule. Explains that jurisdiction is an optional hint and that even mismatched jurisdiction works.

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 begins with a clear verb+resource: 'Fetch forward and backward citation chains for a specific patent.' It distinguishes itself from sibling tools by explicitly naming legal_search_patents_by_keyword and legal_fetch_patent_by_number as 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?

Provides explicit when-to-use statement: 'Use this when building a prior art citation chain for a specific patent you already have.' Also states when to use the sibling tool and includes a fallback reporting mechanism.

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 declares read-only behavior, no side effects, idempotency, and a limit of 10 matches. It adds context beyond annotations by specifying the limits, verified source (EPO OPS + USPTO), and 24-hour cache, which annotations do not cover.

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, starting with purpose, then behavior, then parameters, then return info, then usage guidance. Every sentence is informative, though slightly verbose with the feedback paragraph. It could be tightened but 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?

Despite having an output schema (not shown), the description covers all essential aspects: purpose, parameters, return fields, usage context, limitations (10 matches, 24-hour cache), source verification, and a fallback feedback mechanism. It is complete for an intelligent agent.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing examples for keywords, clarifying options for jurisdiction (EP, US, WO), and noting the default behavior for date_from ('no lower bound'). This goes slightly beyond the schema.

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

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

The description clearly states 'Search patents by keyword across EPO, USPTO, or WIPO', specifying a specific verb and resource. It distinguishes from sibling legal_fetch_patent_by_number by noting that this tool is for keyword-based search without a specific patent number.

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: 'Use this when finding prior art or exploring a technology landscape without a specific number.' It also provides an alternative: 'Use legal_fetch_patent_by_number instead when you have the patent number already.'

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds 'Read-only. No side effects. Idempotent. UK only. 24-hour cache. Verified source.' No contradiction; adds valuable behavioral context.

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

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

Description is comprehensive but includes feedback reporting instructions that could be separated. However, it is front-loaded with the core purpose and remains concise given the amount of useful information.

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

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

With only one parameter, 100% schema coverage, output schema present, and clear description of returns, the tool definition is fully complete for its simple purpose.

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

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

Schema coverage is 100% with a description for the parameter. The description adds format details: '7 digits, e.g. 1234567' and notes it can be a full/partial name, which goes 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?

Description clearly states the tool fetches UK registered charity details by charity number or organisation name. It specifies the verb 'fetch', the resource 'UK registered charity details', and the input type, distinguishing it from sibling tools for US nonprofits.

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 (for UK charities) and when not to (for US nonprofits, recommending alternative sibling tools). Also includes instruction to report feedback if the response 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, openWorldHint, idempotentHint, destructiveHint. The description reinforces these with explicit statements (read-only, no side effects, idempotent) and adds context (US only, 7-day cache, specific return fields, feedback mechanism). 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 informative but somewhat lengthy. However, every sentence serves a purpose (purpose, usage, behavior, params, fallback). Front-loaded with core function. Could be slightly more concise but effective overall.

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

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

Given the presence of an output schema (not shown but indicated) and the tool's simplicity, the description covers all necessary aspects: purpose, parameters, behavioral traits, usage guidelines, and fallback. No gaps.

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

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

Schema coverage is 100% with one parameter (ein) well-described in schema. The description adds value by clarifying the format (with or without dash) and providing examples, improving practical usability.

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 fetches IRS 990 filing data for US nonprofits by EIN. It distinguishes itself from the sibling tool nonprofit_search_nonprofits_by_name, which is used when only a name is available.

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 (when you have exact EIN) and when to use an alternative (nonprofit_search_nonprofits_by_name for name-only queries). Also provides context on data source, caching, and a feedback fallback.

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. Description adds critical context: data source (ProPublica IRS Form 990), rate limit (30/min), no auth required, and return format (trend_direction, CAGR, etc.). 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?

Description is well-organized: purpose, returns, parameters, rate limit, auth, sibling relation, feedback fallback. Each sentence adds value, but it is slightly 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?

Given the presence of an output schema, the description provides sufficient high-level output details, data source, rate limit, auth, and feedback mechanism. It is complete for a 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 coverage is 100% with both parameters fully described. Description repeats the default for years but does not add significant new semantic value beyond the schema.

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

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

The description clearly states it provides a 5-year financial trend for US nonprofits, listing specific outputs like revenue growth, expense ratios, etc. It distinguishes itself from the sibling tool nonprofit_fetch_nonprofit_full_profile.

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

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

The description explicitly says it complements nonprofit_fetch_nonprofit_full_profile for multi-year context, and includes a feedback fallback if the tool doesn't serve the need. It does not explicitly state when not to use, but gives clear context.

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

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

Beyond annotations, the description adds: 'Data refreshed on each call', rate limit of 30/minute, no auth required, and lists output fields. No contradiction with annotations.

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

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

Front-loaded with purpose and key details. Slightly verbose with the report_feedback instruction, but every sentence 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?

Given rich output schema and annotations, the description covers purpose, usage, behavior, parameters, and error handling. No gaps.

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

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

Schema coverage is 100%; the description adds only the example EIN format (already in schema). No additional semantic meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Complete nonprofit due diligence in one call' and lists specific outputs like revenue trends, executive pay, risk flags, and health score. It distinguishes from siblings by implying comprehensiveness.

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

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

The description identifies target users (grant-makers, investors, compliance teams) and provides a recovery mechanism via report_feedback. It does not explicitly state when not to use this tool versus alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: rate limit (30/min), no auth required, returns up to 25 results, uses ProPublica API, and specifies returned data (revenue, assets, health scores). This exceeds annotation coverage.

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

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

The description is well-structured, starting with the core purpose, then details, then usage guidance. It is longer than minimal but every sentence adds value, including the feedback fallback. Could be slightly more concise but is efficient given the information density.

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 2 parameters, an output schema, and clear annotations, the description is comprehensive. It covers purpose, parameters (with mapping), limits, data returned, external API, rate limits, and usage flow. No significant gaps are present.

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 significant value by explaining that category maps to NTEE codes, listing example categories, and noting that raw NTEE letters (A-Z) are also accepted. This clarifies the parameter 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 states the tool's purpose: 'Search US nonprofits by mission category and state.' It specifies the resource (US nonprofits), action (search), and filters (category, state). It also distinguishes itself from siblings by positioning itself as a starting point for due diligence, with a follow-up tool mentioned (nonprofit_fetch_nonprofit_full_profile).

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

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

The description provides clear context for when to use this tool ('starting point for nonprofit due diligence') and explicitly recommends a follow-up tool for deep dives. However, it does not explicitly state when NOT to use this tool, such as when a direct EIN lookup is needed (handled by sibling tool).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'No side effects', 'US only', 'Returns up to 25 matches', '7-day cache', and 'Verified source: IRS EO BMF', providing rich behavioral context 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 well-structured, starting with purpose, then parameter details, usage guidance, and fallback instruction. However, it is slightly verbose due to repetition of annotation-provided traits like 'Read-only. No side effects. Idempotent.' and inclusion of a feedback mechanism that could be separate.

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

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

For a simple search tool, the description covers all relevant behavioral aspects: idempotency, caching, source, output fields, limits, and alternatives. The output schema exists, so return values are not needed in description. Complete for the 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?

Schema coverage is 100% with descriptions for both parameters. The description adds clarity by stating 'Full or partial organisation name' for name and 'Optional, defaults to all states' for state, which are not explicit in the schema.

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

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

The description clearly states the verb (search), resource (nonprofits), and scope (US by name with optional state filter). It distinguishes from sibling tools like fetch_nonprofit_by_ein and search_nonprofits_by_category by specifying when to use each.

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 (when you have a name but not EIN) and when to use the alternative (fetch_nonprofit_by_ein). Also provides context on idempotency, US-only, limit of 25 matches, and a fallback feedback mechanism.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable context: 'Read-only. No side effects. Idempotent. US federal only. Timeout is 30 seconds — large dockets may be slow. Verified source: Regulations.gov + Federal Register fallback. 4-hour cache.' 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 efficient, front-loading the purpose, then providing usage guidance, parameter details, behavioral notes, and a fallback instruction. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (fetching docket details) and the richness of annotations and output schema, the description completes the picture by listing returned fields, caching behavior, timeout, and source reliability. No gaps remain.

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

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

The sole parameter 'docket_id' is fully described in the schema (100% coverage). The description adds formatting examples (e.g., 'EPA-HQ-OAR-2021-0317') that help the agent construct valid values, but the schema already provides a basic description.

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

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

The description starts with 'Fetch full details for a specific regulatory docket by ID,' clearly stating the verb (fetch) and resource (regulatory docket). It differentiates from sibling tools like regulatory_search_open_rulemakings and regulatory_fetch_federal_register_notices by specifying when to use each.

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 ('when you have a docket ID from a search') and when to use the alternative ('Use regulatory_search_open_rulemakings instead when you need to find dockets by topic first'). Also instructs to call report_feedback if the response 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, idempotentHint, destructiveHint. Description adds 'Read-only. No side effects. Idempotent. US federal only. 4-hour cache' and even includes a fallback feedback mechanism for when the tool doesn't serve the user's need, providing rich behavioral context 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 sufficiently detailed but not excessively long. It front-loads the purpose and then provides parameter details, usage guidance, and additional context. Every sentence adds value, though it could be slightly more concise by consolidating some redundancies.

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 3 parameters (1 required), has output schema (return fields listed), multiple siblings, the description covers all needed aspects: parameter defaults, caching behavior, source verification, fallback feedback, and alternative tool references. No gaps identified.

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. Description adds examples for each parameter (e.g., 'SEC', 'cryptocurrency', '2024-01-31') and specifies defaults ('defaults to all notices', 'defaults to last 90 days'), which provides practical meaning beyond schema descriptions.

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

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

Clearly states 'Fetch recent Federal Register notices and rules for a specific agency.' Explicitly distinguishes from sibling tool 'regulatory_search_open_rulemakings' by specifying when to use that alternative. The verb 'fetch' and resource 'Federal Register notices' 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?

Provides explicit guidance: 'Use this to monitor recent regulatory activity for an agency. Use regulatory_search_open_rulemakings instead when filtering by topic across all agencies.' Also notes US federal only, verified source, and 4-hour cache, giving agents clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds 'Read-only. No side effects. Idempotent. US federal only.' and '4-hour cache' and 'Verified source'. 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 with front-loaded purpose but is slightly verbose due to embedded parameter descriptions and feedback instructions. However, it earns its length by packing necessary detail.

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

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

Given the tool's complexity (search with parameters, output schema exists), the description fully addresses purpose, usage, parameters, return values, caching, source verification, and even error handling via report_feedback.

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 adds valuable context: examples for keyword, agency abbreviations, defaults, and status options. It also describes return fields, exceeding what the schema provides.

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

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

The description clearly states the tool searches open rulemakings and public comment periods on Regulations.gov and the Federal Register. It explicitly notes read-only, idempotent, and US federal scope, distinguishing it from siblings like regulatory_fetch_docket_details.

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 monitoring regulatory activity on a topic' and points to alternative regulatory_fetch_docket_details when a docket ID is available. It also includes a fallback to call report_feedback if the response 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?

The description indicates a write operation ('Report'), but annotations set readOnlyHint=true, suggesting no side effects. This is a contradiction as submitting feedback likely involves data storage. The description does not clarify this inconsistency or disclose the actual behavioral 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 verbose but well-structured with clear sections and examples. It front-loads the purpose and then details each parameter. A slightly more compact presentation could improve readability, but 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?

Given the availability of a detailed input schema and output schema (inferred from context), the description fully complements these with usage context, parameter details, and constraints. It leaves no significant gaps for an agent to misinterpret.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant value by explaining parameter usage, providing examples, stating character limits, and clarifying when to use optional fields like intended_query and gap_description.

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

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

The description clearly states the tool's purpose: reporting data quality issues or agent intent gaps for DataNexus tool responses. It uses a specific verb ('Report') and identifies the resource ('data quality issue or agent intent gap'), distinguishing it from sibling tools that primarily fetch data or generate API keys.

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 on when to use this tool, including when to set feedback_type to 'agent_gap' versus 'user_feedback'. It also includes an example of a typical call, helping the agent understand usage context.

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

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

Annotations already specify readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds further behavioral context by detailing the return values (status, message, tool_id, upgrade_url) and provides an example call, which is well beyond what annotations offer.

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

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

The description is four sentences, front-loaded with the main purpose. Each sentence adds value: purpose, parameter explanation, return details, and example. There is no fluff or redundancy.

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

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

Given the tool's simplicity (one parameter, read-only check), the presence of an output schema, and clear annotations, the description fully covers what an agent needs to know. It explains what the tool does, what input to provide, and what to expect in return.

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 parameter with 100% description coverage, so baseline is 3. The description adds an example and reiterates the parameter's purpose, which provides marginal additional value but does not significantly enhance understanding 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 starts with 'Check MCPize subscription status for a DataNexus tool,' which uses a specific verb and resource. None of the sibling tools are related to subscription status, so it is well-distinguished.

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

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

The description clearly states the required parameter and how to use it ('Pass the tool the user is asking about'). However, it does not explicitly mention when not to use this tool or list alternatives, which would be helpful but is not critical given its unique purpose.

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

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

The description adds significant behavioral context beyond annotations: it reduces context from 40000 to 800 tokens, returns matching tool names and parameter hints, and explicitly states it is read-only and has no side effects. Annotations already indicate readOnlyHint and idempotentHint, but the description enriches understanding of operational 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 efficiently structured: it starts with the tool's core purpose, then states safety (read-only), then usage instructions, parameter details, and finally constraints and fallback actions. Every sentence contributes unique 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?

Given the tool's meta-purpose and the presence of an output schema, the description covers all necessary aspects: what it returns, how it reduces context, when to use it, restrictions on recursion/validation, and a clear path for failure cases. It leaves no ambiguity for the agent to invoke it correctly.

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

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

Schema description coverage is 100% for both parameters. The description provides added value by restating the query parameter with concrete examples like 'check if a Python package has CVEs' and clarifying the domain parameter's optional nature and allowed values. This goes beyond the schema's minimal descriptions, aiding the agent in formulating queries.

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

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

The description clearly states the tool's purpose: finding the right DataNexus tool by describing a task in plain English. It distinctly positions itself as a meta-tool for tool discovery, differentiating it from its many sibling tools that perform specific domain tasks.

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: 'Call this before any other DataNexus tool to reduce context load.' It also specifies when not to use it: 'Do not call this recursively or to validate results — use validate_tool_output for that.' Additionally, it provides a fallback mechanism for unexpected results via report_feedback.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: no network call for spdx_ids path, deps.dev resolution with max 10 concurrent, max 50 items, rate limit, and no auth. 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: purpose first, then behavior details, constraints, target users, and fallback. It is slightly lengthy but every sentence adds value. Minor redundancy in stating 'max 10 concurrent' and 'max 50 items' could be merged, but overall efficient.

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

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

Given the tool's complexity (two input modes, external dependencies, rate limits), the description covers all essential aspects: purpose, behavior, constraints, output type, and intended audience. It also provides a feedback fallback. The existence of an output schema means return details are not required.

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

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

Schema coverage is 100% with parameter descriptions. The description enhances understanding by explaining the two input paths: packages (with ecosystem) for dynamic resolution, and spdx_ids for static lookup. It clarifies that packages require deps.dev calls while spdx_ids do not.

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

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

The description clearly states the tool's purpose: auditing licence compatibility of dependency lists. It specifies input types (package names or SPDX IDs) and output (COMPATIBLE/CONFLICT verdict). It also distinguishes from siblings by mentioning the static SPDX table and deps.dev resolution, which are unique.

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 context: intended for developers and compliance teams, max 50 items, rate limit 60/min, no auth. It also suggests fallback to report_feedback if needed. However, it does not explicitly contrast with other license tools like security_fetch_licence_analysis, but the niche is clear.

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

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

Description adds significant behavioral context beyond annotations: silent permanent watch, uses OSV.dev and Redis, 90-day TTL, input size limit 500 KB, rate limit 10/min, no auth required. None of this contradicts annotations; destructiveHint=true aligns with deregister action.

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

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

Description is informative but somewhat lengthy; front-loads the main purpose. Could be slightly trimmed, but every sentence adds value.

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

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

Given the tool's complexity (persistent watch, multiple actions, constraints), the description covers return signals, limitations, and use case. Output schema exists, so return format is sufficient.

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

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

Schema coverage is 100% with all parameters described. The description adds meaningful context: sbom is only required for register, watch_id should be unique, and actions are register/check/deregister.

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: 'Persistent SBOM watch. Register once, check anytime for new CVEs.' It specifies the verb 'watch' and distinguishes from one-time scans and license checks among siblings.

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

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

The description provides clear context: 'For DevSecOps teams monitoring production dependency exposure.' It also includes a note on calling report_feedback if inadequate. However, it does not explicitly specify when not to use this tool vs alternatives.

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

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

Beyond annotations (readOnly, idempotent), the description discloses constraints (500 KB max, exact SPDX IDs only), default policy behavior, unlisted license handling (default WARN), caching (1-hour), and data source (deps.dev), providing comprehensive behavioral context.

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

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

The description is dense but well-organized, with purpose first, then parameters, returns, alternatives, and miscellany. Every sentence adds value, though slightly verbose for the most concise possible version.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all necessary aspects: input constraints, default policies, return structure, caching, source, and feedback mechanism, leaving no critical gaps.

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

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

With 100% schema coverage, the description adds significant value by specifying format requirements (CycloneDX or SPDX JSON), size limit, policy default structure, exact ID requirement, and return fields, far exceeding 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?

The description explicitly states the tool audits a CycloneDX or SPDX SBOM against a license policy and returns a PASS/WARN/BLOCK verdict, clearly differentiating it from sibling tools like 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 explicitly directs users to use security_audit_sbom_vulnerabilities for CVE auditing instead, and provides a fallback procedure via report_feedback if the response 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds non-redundant behavioral details: mentions large SBOMs may take up to 10 seconds, returns CVEs grouped by package, and a 1-hour cache. It reinforces the read-only, no-side-effects, idempotent nature without contradicting annotations.

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

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

The description is well-structured and mostly efficient, but slightly verbose with redundant confirmations of read-only and idempotent nature already covered by annotations. However, every sentence adds value (usage guidance, parameter details, cache info). It loses a point for minor repetition but 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?

Given the complexity of auditing an SBOM, the description covers all key aspects: input format and requirements, performance expectations, output structure (CVEs grouped with severity and fixed versions), caching behavior, and clear alternatives. The presence of an output schema (signaled in context) further complements completeness. No gaps are apparent.

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

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

Schema coverage is 100% for the single required parameter sbom_json. The description adds meaning beyond the schema: specifies accepted formats (CycloneDX or SPDX), mentions performance impact for large SBOMs, and explains the return format (CVEs grouped). This significantly aids the agent in understanding the parameter's scope and behavior.

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

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

The description starts with 'Audit a Software Bill of Materials for known vulnerabilities across all listed packages,' clearly stating the verb (audit), resource (SBOM), and scope (all packages). It distinguishes from sibling tool security_fetch_package_vulnerabilities, which checks single packages. The description also mentions the verified source and caching, adding further clarity.

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 ('when you have a full SBOM to audit') and when to use an alternative ('Use security_fetch_package_vulnerabilities instead when checking a single package version'). It also provides a fallback mechanism via report_feedback, giving complete guidance on usage context.

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

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

Annotations already indicate read-only and idempotent, but description adds cold-start fetch time (≤30s), rate limit (60/min), no auth requirements, and storage details (PyPI/npm stats in Redis). 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?

Description is clear and well-organized, covering action, algorithm, output, infrastructure, limitations, and fallback. The feedback instruction adds length but is valuable. Could be slightly more concise by merging some sentences.

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

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

Covers behavior, rate limits, auth, cold start, and intended use case. Minor gaps: does not explain behavior for packages not in top-10k or error handling for unsupported ecosystems (schema already restricts). Overall sufficient 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?

Input schema has 100% coverage for both parameters (package_name and ecosystem with enum). Description does not add extra meaning to parameters beyond what the schema provides, but the overall tool operation is contextualized.

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

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

Clearly states it detects typosquatting attacks, specifies the algorithm (Damerau-Levenshtein distance ≤ 2), scope (top-10,000 packages), and output (similar_packages with scores and verdict). Distinguishes from sibling frontend_security_detect_typosquatting by targeting supply-chain security engineers.

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 target users ('security engineers auditing supply-chain package names before inclusion') and provides a feedback mechanism if the tool doesn't serve the user's need. Does not explicitly contrast with alternatives but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description confirms these traits with 'Read-only. No side effects. Idempotent.' and adds context about the data source ('Verified source: CISA KEV catalog, updated daily, cached'). 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 efficiently packed with purpose, safety, parameters, return fields, sibling comparisons, source info, and feedback instruction. Front-loaded with core purpose, 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?

Given the presence of an output schema, the description still lists return fields and explains the tool's role in the CVE triage flow. It provides complete context for a simple single-parameter tool, including fallback direction.

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

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

Schema coverage is 100% with a description for cve_id. The description reinforces the format and required nature, and provides an example (CVE-2021-44228), adding value beyond the schema alone.

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

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

The description clearly states the verb 'Check', the resource 'CISA KEV catalog', and the scope 'whether a CVE is in it'. It explicitly distinguishes from sibling tools like security_fetch_cve_detail and 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?

The description provides explicit when-to-use guidance: for checking KEV status (active exploitation). It also specifies alternatives: use security_fetch_cve_detail for full severity and security_fetch_cve_epss for exploit probability. Includes a feedback fallback mechanism.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds useful context: '1-hour cache' and 'Verified source: NIST NVD', which go 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?

Well-structured, front-loaded with purpose, then details, usage, source, cache, fallback. Every sentence adds value, 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?

Covers purpose, parameter, return fields summary, source, caching behavior, and feedback mechanism. Output schema exists, so return details are adequate. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds format detail (CVE-YYYY-NNNNN) but mostly repeats schema. No significant added value beyond schema.

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

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

Clearly states 'Fetch full detail for a specific CVE by ID' with verb and resource. Explicitly distinguishes from sibling tool security_fetch_package_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?

Provides explicit when to use ('when you have a CVE ID') and when not to ('use security_fetch_package_vulnerabilities instead'). Includes a feedback fallback for mismatched needs.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: caching interval (6-hour), data source (FIRST.org), and the specific return fields (epss and percentile), surpassing what annotations cover.

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 yet comprehensive: front-loaded purpose, then parameter, returns, thresholds, integration advice, source, cache, and an example. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one parameter, the description covers all essential aspects: what it does, how to use it, what it returns, practical thresholds, and complementary tool recommendation. The presence of an output schema (not shown) further reduces the need for return format 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% with a brief description for cve_id. The description adds an example value and explains the return format, thresholds, and usage context, which enriches the parameter meaning 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 tool fetches the EPSS exploit probability score for a CVE, predicting exploitation likelihood in the next 30 days. It distinguishes its role from sibling tools like security_fetch_cve_detail by contrasting EPSS (urgency) with CVSS (severity).

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 advises combining with security_fetch_cve_detail to prioritize patching, clarifying when to use this tool. It also provides threshold-based action guidance. However, it does not explicitly exclude scenarios where this tool should not be used, but the context is clear.

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

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

Adds rate limit (60/min), no auth required, explanation of UNKNOWN status, and parallel call behavior. Annotations already indicate read-only and idempotent, so description complements them well.

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 main purpose, includes usage and feedback instructions. Slightly lengthy but each sentence adds value; could be more concise but still efficient.

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

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

Covers purpose, behavior, usage scenario, error handling, rate limit, auth, and feedback path. With output schema present, no missing critical information for a single-parameter 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% and description does not add extra parameter details beyond the schema's example. Baseline 3 is appropriate as 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?

Clearly states it combines CVSS, CISA KEV, and EPSS to return a risk verdict, with specific levels (CRITICAL_EXPLOIT, etc.). Distinguishes from siblings like security_fetch_cve_detail and security_fetch_cve_epss by being a combined summary.

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

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

Specifies the tool is for security engineers triaging vulnerabilities after fetch_cve_watch fires, and provides a fallback feedback mechanism. Lacks explicit comparison to other CVE tools but context is clear.

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

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

Beyond annotations (destructiveHint=true), the description adds critical behavioral context: uses Redis for persistence, daily background refresh from NVD/CISA KEV/EPSS, rate limit 60/min, no auth required. No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose, then details on behavior, return format, rate limit, and audience. It is informative but slightly verbose; could be trimmed while retaining clarity.

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

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

Given tool complexity (3 actions, persistence, refresh), the description fully covers lifecycle, return fields, and usage constraints. Output schema exists and is referenced. No gaps identified.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining action types and their context (e.g., 'cve_ids required for create'), and clarifies watch_id as unique identifier, providing value beyond the schema.

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

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

The description clearly states the tool's purpose: managing a persistent CVE watchlist with actions create, check, delete. It distinguishes from siblings like security_fetch_cve_detail by emphasizing persistence and event tracking over time.

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 specifies target users ('security engineers tracking CVE exposure'), usage pattern ('Create once, check anytime'), and provides a fallback instruction to report_feedback. However, it does not explicitly compare to alternatives or state when not to use.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details internal behavior: per-user cursor in Redis, first call returning 30 days, subsequent calls returning only new events, no external API calls, instant response. 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 efficiently structured, starting with the main purpose, then explaining efficiency, parameter, behavior, and sources. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description thoroughly covers purpose, parameter semantics, behavior, cursor mechanism, sources, and even a fallback action. It leaves no significant gaps.

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

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

The schema describes watch_ids with a basic example. The description adds crucial context: these are the same IDs used when creating watches with security_fetch_cve_watch. Since schema coverage is 100%, baseline is 3, but the extra linkage raises the score.

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

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

The description clearly states the tool checks all specified CVE watches for new events since the last poll, uses a per-user cursor, and returns only watches with new events. It explicitly references the sibling tool security_fetch_cve_watch for creation, distinguishing their roles.

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

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

The description explains it is efficient for scheduling and specifies the relationship to the creation tool, implying when to use it. It also provides a fallback to report_feedback if results are insufficient. However, it does not explicitly mention when not to use it or list alternative tools beyond the implicit 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description adds 'Hard 8-second timeout — large dependency trees may return partial results', '1-hour cache', and 'Read-only. No side effects. Idempotent.'

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

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

Description is well-structured and front-loaded with essential action and constraints. It is slightly verbose but every sentence adds value: purpose, parameters, usage guidance, source, cache, fallback. No redundant information.

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

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

Given the tool's complexity (transitive dependency tree, timeout), description covers purpose, parameters, usage, constraints, source, cache, and fallback. Output schema exists but description also notes return value ('all direct and transitive dependencies with version constraints').

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. Description adds examples for package ('requests'), version ('2.28.0'), and lists ecosystem values ('One of PyPI, npm, Maven, Go, Cargo, NuGet, RubyGems'), enhancing beyond schema.

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

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

Description clearly states 'Fetch the full dependency tree for a package version including transitive dependencies', specifying verb, resource, and scope. It distinguishes from sibling 'security_fetch_package_vulnerabilities' by noting when to use each.

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 tells when to use this tool ('understand full supply chain exposure') and when to use an alternative ('only need CVEs for a single package'). Also mentions source (deps.dev), cache duration, and fallback feedback mechanism.

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 declare readOnly, openWorld, idempotent, non-destructive. Description adds concrete behavioral details: static bundle for top-50 licences, fallback to spdx.org API, risk levels assume proprietary/commercial use, rate limit 60/min, no auth required. No contradiction with annotations; description enriches understanding.

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

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

Description is informative yet compact. Front-loads core functionality, then adds details. Includes feedback fallback which is useful but slightly lengthens text. No redundant or empty sentences. Good structure for quick scanning.

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?

Tool has one required parameter, rich annotations, and an output schema (implied). Description covers all behavioral aspects: source types, fallback, audience, rate limits, auth. No gaps for a simple lookup tool.

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

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

Only one parameter (spdx_id) with schema coverage 100%. Schema description already defines it as 'SPDX licence identifier e.g. MIT, Apache-2.0, GPL-3.0. Required.' Tool description repeats examples but adds no new semantics. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Describes exactly what the tool does: explains any software licence, returns obligations, permissions, limitations, risk level, and OSI/FSF status. Specifies input (SPDX identifier). Clearly distinguishes from siblings by focusing on comprehensive licence analysis rather than just fetching text or checking compatibility.

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?

States target users (security engineers, developers) and context (before including a dependency). Mentions fallback behavior and rate limit. Includes explicit guidance to call report_feedback with specific arguments if tool fails to serve the user's need. Lacks explicit comparison to sibling tools for when not to use this tool, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description reinforces these by stating 'Read-only. No side effects. Idempotent.' It adds additional context: 'Verified source: deps.dev (Google). 1-hour cache.' 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 well-structured and front-loaded with purpose and parameters. It is concise but includes all necessary information. Could be slightly shorter, but still 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?

Given the rich annotations and output schema, the description is complete. It covers the tool's purpose, required parameters, usage guidance, alternative, caching, source verification, and feedback mechanism. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for package and version, listing ecosystem options, and explaining the return value. This exceeds what the schema 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?

Clearly states it fetches the SPDX licence identifier for a given open source package version. Includes specific verb and resource, with examples and distinction from sibling tools like security_fetch_package_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?

Explicitly tells when to use this tool (verify licence compatibility before including a dependency) and when to use an alternative (security_fetch_package_vulnerabilities for security issues). Also provides feedback instructions if the tool doesn't meet 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 (readOnlyHint, idempotentHint, etc.) are already present, and the description adds useful context: 'data refreshed on each call, 1-hour cache', rate limit, and no auth. 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?

Description is about 5 sentences, front-loaded with purpose and key details. The fallback instruction is appended but not excessive. Good balance of information.

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

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

Lists return fields (e.g., anomaly_score range, maintainer_health enum), data sources, caching, rate limits, and auth. For a tool with output schema, this provides sufficient context beyond the schema.

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

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

Schema coverage is 100%, but the description mentions only 'npm or PyPI' while the schema includes 'cargo' and 'go', potentially causing confusion. Baseline 3 is appropriate for a schema that covers parameters, but the mismatch reduces clarity.

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 ('Analyse ownership and release history') and the goal ('detect supply-chain risk') for npm or PyPI packages, distinguishing it from sibling tools like security_fetch_package_risk_brief.

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 targets security engineers auditing dependencies for production builds, and includes fallback guidance (report_feedback) for non-serving responses. Lacks explicit when-not-to-use but context is clear.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds that data is refreshed on each call, states a rate limit of 30/minute, notes no authentication required, and lists the exact return fields. 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 compact at about four sentences, front-loaded with the main purpose. It covers key details without redundancy.

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

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

Given the presence of an output schema, the description lists all key return fields and data sources. It provides sufficient context for an agent to understand tool behavior and output, missing only a note on how to interpret the verdict.

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 parameters are fully described. The description adds minimal extra meaning; however, it incorrectly states the version parameter as 'Required.' (schema marks it optional), causing a slight inconsistency.

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

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

The description clearly states it returns a single SHIP/CAUTION/BLOCK verdict for any package, combining CVEs, license, maintainer health, and transitive count. It specifies the data sources (OSV.dev, deps.dev, PyPI, npm registry) and distinguishes itself from sibling security tools by offering a consolidated risk brief rather than individual vulnerability or license checks.

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

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

The description explicitly targets 'security engineers performing pre-inclusion package review,' providing clear context. It does not explicitly list when to avoid using the tool or suggest alternatives, but the niche is well-defined.

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, etc.), the description adds substantial behavioral context: it explicitly states 'Read-only. No side effects. Idempotent.', mentions a 1-hour cache, identifies Google OSV.dev as the source, and explains batch response semantics (partial flag, failed_count). No contradiction with annotations.

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

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

The description is compact but information-dense. The opening sentence states the core purpose, followed by structured mode explanations. Every sentence adds value—from mode-specific behavior to return format to fallback instructions. No wasted words or tautology.

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

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

Given the tool's complexity (dual modes, batch limits, multiple return fields) and the presence of an output schema, the description fully covers what an agent needs: mode selection, parameter semantics, result shape, and error fallback. It is self-sufficient and leaves no critical gaps.

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

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

Even though schema description coverage is 100%, the description adds crucial semantic detail: it explains the relationship between single-package fields and the packages array, clarifies which fields are ignored in batch mode, and describes the batch object structure ({name, version, ecosystem}). This goes well beyond the schema's individual field descriptions.

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

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

The description starts with a specific verb and resource: 'Fetch all known CVEs for an open source package version or a batch of packages.' It clearly distinguishes between single-package and batch modes, and differentiates from sibling tools like 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?

Explicit usage guidance is provided: single-package mode vs batch mode, the 50-item batch limit, and the fact that batch mode overrides single parameters. It also names specific alternatives for related needs (security_fetch_cve_detail, security_audit_sbom_vulnerabilities) and even includes a fallback instruction to call report_feedback 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?

Annotations already indicate read-only and non-destructive nature. Description adds 'Never blocks' and explains the two-layer agreement condition before feedback is filed, enriching behavioral context 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?

Description is slightly verbose but well-structured: starts with core purpose, then parameter details, then usage guidance. Every sentence adds value; minor redundancy could be trimmed.

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 output schema existence, description doesn't need to detail returns but mentions key outputs (pass, issues_found, feedback auto-filed). Covers all aspects: purpose, parameters, usage context, and fallback action.

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 description adds inline explanations for each parameter (e.g., where to find tool_id, purpose of query_hash), surpassing the schema's own descriptions.

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

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

Description clearly states the tool validates DataNexus tool responses for data quality using two-layer validation. It specifies the verb 'validate' and resource 'DataNexus tool response', differentiating it from siblings like report_feedback.

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 when to use this tool versus report_feedback, including a concrete alternative and guidance for handling insufficient responses. Provides clear context for choosing between tools.

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