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

The description adds significant behavioral context beyond annotations (all false): key shown only once, rate limits, and usage via X-Api-Key header, which are crucial for proper invocation.

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, structured with the main action first followed by details and rate limit, every sentence adds necessary information without redundancy.

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

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

The description is complete for an API key generation tool, covering return behavior (shown once), storage instruction, and usage in subsequent requests; output schema likely provides further return details.

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

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

The single parameter 'email' is well-described in both schema and description; description adds value by explaining the key's purpose and subsequent usage, beyond the schema's basic requirement.

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 generates an API key for a given email address, with specific verb 'Generate' and resource 'DataNexus API key', distinguishing 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?

Provides clear guidance on when to use (anonymous vs registered callers, rate limits) and implies context for use, but does not explicitly contrast with 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds valuable context beyond annotations: 'Permanently revoke', 'key will stop working immediately', 'cannot be undone', and the need for human confirmation. 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?

Three sentences, front-loaded with a crucial warning about destructiveness and human confirmation. Every sentence serves a purpose without redundancy. Highly efficient.

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

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

The tool is simple (1 parameter, output schema exists). The description covers purpose, irreversibility, immediate effect, and safety requirement. It could mention idempotency (that revoking an already revoked key has no effect), but the annotation covers that. Overall fairly complete.

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

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

Schema coverage is 100% and the schema already describes the parameter ('API key (dnx_...) to permanently revoke. Required.'). The description does not add semantic detail beyond what the schema provides, so baseline score is appropriate.

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

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

The description explicitly states the action ('revoke'), the resource ('DataNexus API key'), and the immediate consequence ('will stop working immediately'). It clearly distinguishes from sibling tools like apikeys_generate_api_key and apikeys_rotate_api_key by focusing on permanent removal.

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

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

The description provides a strong guideline: 'requires human confirmation before use in automated pipelines.' It warns of irreversibility. However, it does not explicitly contrast with alternatives like generate or rotate, missing a clear 'when to use vs not use' statement.

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 significant behavioral context beyond annotations: requires human confirmation, returns new key only once (must be stored immediately), and specifies header usage. Annotations already indicate destructive=true, but description enriches with operational details.

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

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

Two sentences plus a warning symbol, no redundancy. Critical information (destructive, human confirmation, store key) is front-loaded. Every word serves a purpose.

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

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

With an output schema present and only one simple parameter, the description adequately covers purpose, safety, and key operational instructions. No missing information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema's parameter description. The note about passing keys in header is general, not param-specific. Baseline 3 is appropriate.

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

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

Description clearly states 'Revoke the current API key and issue a replacement', specifying a verb (revoke/replace) and resource (API key). It distinguishes from siblings like apikeys_generate_api_key (create new) and apikeys_revoke_api_key (only revoke).

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 requires human confirmation in automated pipelines. Implies usage when rotating a key, but does not explicitly contrast with using revoke then generate separately.

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, destructiveHint, idempotentHint, openWorldHint. Description adds: US only, fuzzy name match, 24-hour cache, verified source SAM.gov, and fallback instruction to report_feedback. 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?

Description is thorough but not overly verbose. Each sentence adds value (purpose, usage, param help, alternative, caching, fallback). Could be slightly shorter but 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 one required param and output schema exists, description covers return fields (excluded, type, dates), caching, source, and error handling. Complete for 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?

Only one parameter name_or_ein. Description adds format (9-digit EIN with dash example), clarifies required, explains fuzzy match behavior, and suggests verifying with EIN. Schema coverage 100% but description adds significant nuance.

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 checks US federal exclusions list (debarred from government contracts). Explicitly distinguishes from sibling tool govcon_search_contract_awards by stating its purpose is to find contracts won, not checks exclusions.

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 'Use this before awarding federal contracts or grants.' Provides alternative: 'Use govcon_search_contract_awards instead to find what contracts an entity has won.'

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?

Descriptively states 'Read-only. No side effects. Idempotent. US only.' Adds caching ('24-hour cache') and source verification ('Verified source: FINRA BrokerCheck'), going beyond annotations. No contradictions.

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

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

Every sentence adds value: purpose, properties, usage guidance, alternatives, error handling. Well-organized and front-loaded with essential info.

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 single parameter, rich annotations, and output schema, the description fully covers purpose, usage, return data (registration status, qualifications, etc.), caching, and fallback instructions.

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?

Describes crd_number as 'Central Registration Depository number as a string of digits e.g. 1234567. Required.', adding format clarity and limitation ('name lookup not supported') 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?

Specific verb 'Fetch' and resource 'FINRA BrokerCheck registration' by CRD number clearly states the action. Explicitly distinguishes from sibling tool 'compliance_search_npi_by_name' for healthcare providers, and mentions US-only scope.

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

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

Explicitly states when to use: 'when you have the CRD number'. Provides alternative 'Use compliance_search_npi_by_name instead for healthcare providers'. Also gives post-use error handling instruction for 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 provide readOnlyHint, idempotentHint, etc. Description adds context: no side effects, 24-hour cache, verified source (NPPES), and feedback fallback. 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 front-loaded with key purpose and usage, then details. Slightly long but well-structured, every sentence adds value. Inclusion of feedback fallback is extra.

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 essential aspects: purpose, usage, parameters, alternative, source, caching, output summary, and error handling via feedback. Complete for a single-param tool with good annotations.

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

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

Schema already covers the parameter description (100% coverage). Description reinforces format (no dashes) and examples, but does not add new 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?

Clearly states the tool fetches NPI registration details by NPI number, specifies it is read-only, idempotent, and US only, and distinguishes from sibling tool compliance_search_npi_by_name.

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 (have exact NPI) and when to use the alternative (compliance_search_npi_by_name for name search), plus formatting tip on dashes.

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, destructiveHint, idempotentHint), the description adds specific traits: 'Read-only. No side effects. Idempotent. US only. Returns up to 10 matches. 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 purpose, but includes a lengthy feedback instruction. While informative, it is slightly verbose for a concise description.

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

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

The description covers source, constraints, output fields, cache behavior, and error handling via feedback, making it fully complete given the tool's complexity and rich annotations/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% with parameter descriptions. The description repeats these with minor additions (e.g., 'e.g. CA'), but adds no significant new semantic value beyond what the schema already provides.

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

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

The description explicitly states it searches the NPPES NPI Registry by provider name with optional filters, and distinguishes itself from the sibling tool 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?

Provides clear when-to-use ('when you do not have the NPI number') and when-not-to-use (use compliance_fetch_npi_provider for exact NPI), plus constraints like US-only and up to 10 matches, 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?

Description adds significant behavioral context beyond annotations: live DNS via Cloudflare DoH, no cache, and detailed scoring logic for SPF/DMARC/DKIM. 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?

Concise, well-structured with clear sections, scoring details, and an example. No wasted words.

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

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

Fully covers purpose, parameter, scoring methodology, and return structure. Output schema exists, so return values need not be repeated.

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 describes the domain parameter (100% coverage), but description reinforces format (no protocol) and provides example.

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

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

Description clearly states it checks SPF, DMARC, and DKIM email authentication for a domain, differentiating it from other DNS-related tools like 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?

Description implicitly indicates usage for checking email authentication, but lacks explicit guidance on when not to use or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value beyond annotations by disclosing the data source ('Verified source: Cloudflare DoH'), caching behavior ('4-hour cache'), and the read-only, side-effect-free, idempotent nature. No contradictions with annotations.

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

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

The description is concise but comprehensive. It front-loads the core purpose and important characteristics (read-only, idempotent), then provides parameter details, usage comparison, source, caching, and fallback. Every sentence adds value without repetition.

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

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

Given the tool's complexity (fetching DNS records), annotations (readOnly, idempotent), and existing output schema, the description covers all necessary aspects: purpose, parameters, usage context, data source, caching, and fallback. It leaves no gaps for an AI agent to misuse.

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

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

Input schema covers 100% of parameters with descriptions. The description adds further clarity by providing examples ('e.g. cloudflare.com'), listing valid record types, and giving an example array. While the schema already describes the parameters, the description enriches them with practical usage details.

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 current DNS records for a domain via Cloudflare DNS over HTTPS. It uses specific verbs ('Fetch', 'resolve') and explicitly names the resource ('DNS records for a domain'). It also differentiates from the sibling tool domain_fetch_domain_rdap by contrasting DNS records vs registration metadata.

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 ('when you need live DNS resolution') and when not to ('Use domain_fetch_domain_rdap instead when you need registration metadata'). It also includes a fallback instruction to call report_feedback if the tool does not serve the user's need, demonstrating thorough usage guidance.

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

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

Description goes beyond annotations by specifying read-only, idempotent, no side effects, source (crt.sh), cache duration (4 hours), and return format. All annotations are reinforced and supplemented.

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 verbose. It front-loads the purpose and behavior, and each sentence adds value. Could be slightly tighter, but still well-structured.

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

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

For a simple one-parameter tool, the description covers purpose, usage guidance, behavioral details, parameter semantics, source, cache, and fallback. The presence of an output schema complements the described return format.

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 single parameter. The description repeats the parameter info with an example, adding slight value but not significantly beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states the action (fetch historical SSL cert issuance), resource (domain from CT logs), and distinguishes from sibling domain_fetch_ssl_certificate_chain. The verb 'fetch' and resource 'domain history' are specific.

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

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

Explicitly states when to use (detect hijacking, audit), when not to (use sibling for current cert), and provides fallback instruction via report_feedback. Contexts are clear and helpful.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context: 'Read-only. No side effects. Idempotent.' Also describes return fields 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?

Efficiently front-loaded with main action and key details. Every sentence adds value: usage guideline, parameter hint, alternative tools, source, cache, feedback mechanism. No fluff.

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

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

Given simple tool with 1 param, full schema coverage, good annotations, and existing output schema, the description is fully complete: it explains purpose, usage, return content, caching, and provides fallback feedback mechanism.

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 clear description. Description adds a concrete example ('example.com not https://example.com') and clarifies required format, providing additional 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?

Clearly states 'Fetch domain registration details via IANA RDAP' with specific verb and resource. Distinguishes from sibling tools like domain_fetch_ssl_certificate_chain and domain_fetch_dns_records by specifying different use cases.

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 ('when you need registration metadata') and when not to use with named alternatives. Also includes caching info and a feedback instruction 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?

The tool already has annotations (readOnlyHint, idempotentHint) and the description adds details beyond annotations: IPv6 limitation, daily quota, caching, and API source. No contradictions found.

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 each sentence adds value. Slightly verbose but effective. Could be tightened slightly without losing clarity.

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

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

Given the tool's simplicity (one parameter, no nested objects) and presence of output schema, the description covers all necessary context including limitations, caching, and error handling.

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 is fully documented in schema (100% coverage). The description adds context about domain resolution to IPv4, which is not in the schema.

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

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

The description clearly states the tool performs reverse IP lookup to find co-hosted domains. It explicitly mentions the input type and use cases, distinguishing it from sibling tools like 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?

The description explains when to use the tool and what input to provide. It mentions daily quota and fallback feedback mechanism. However, it does not explicitly list alternatives or when not to use it.

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

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

The description adds behavioral context beyond annotations: it declares 'Read-only. No side effects. Idempotent.' (matching annotations), mentions a 4-hour cache, and specifies the data source (crt.sh Certificate Transparency). It also describes the return fields (issuer, subject, validity period, SANs). 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, parameter details, usage guidance, and fallback. Every sentence adds value, but it is slightly verbose due to the feedback instruction. Still efficient for the information conveyed.

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 simplicity (one parameter, output schema present), the description covers all necessary aspects: purpose, parameters, return fields, usage context, alternative, data source, caching, and a feedback mechanism for gaps. No missing information.

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%, providing a baseline of 3. The description adds meaningful clarification: 'Domain name without protocol e.g. github.com. Required. Does not support IP addresses or wildcard domains.' This adds constraints not fully captured by the schema description, earning a 4.

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

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

The description clearly states the action ('Fetch SSL certificate history') and the resource ('from Certificate Transparency logs'). It distinguishes itself from sibling tools by explicitly naming domain_fetch_domain_rdap as an alternative for registration data. It also specifies limitations (no IPs/wildcards), which further clarifies its scope.

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

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

Provides explicit guidance on when to use ('detect unexpected certificate issuance or audit certificate history') and when to use an alternative ('Use domain_fetch_domain_rdap instead when you need registration data'). Also includes fallback instructions for if the tool does not suffice, guiding the agent to 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, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable context: no side effects, caching with 24-hour TTL, circuit breaker mechanism, fallback sources, and response includes source field. 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 detailed but well-structured, front-loading the core purpose. It covers sources, caching, error handling, and fallback. Could be slightly shorter by consolidating some details, but overall 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?

The description covers all critical aspects: data sources, caching, error handling, idempotency, and even a fallback action (report_feedback). With an output schema present, return value details are not needed. The description is thorough for this tool's complexity.

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

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

The input schema has 100% coverage for the single parameter 'domain'. The description repeats the schema's description but adds no new semantic detail (e.g., format, validation). 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?

The description clearly states the tool enumerates subdomains via Certificate Transparency logs. It specifies the primary source (crt.sh) and fallback (RapidDNS), and the verb 'enumerate' is precise. This differentiates it from sibling tools like 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?

The description explains when to use the tool (subdomain enumeration) and provides context on caching and fallback behavior. It also explicitly instructs to call report_feedback if the result doesn't serve the user's need. However, it lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds behavior beyond annotations, notably that ${{ secrets.FOO }} and ${{ env.FOO }} references are NOT flagged, only literal secrets. Also specifies size limit (500 KB) and output structure (risk_level, findings).

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

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

The description is front-loaded with the action, then parameters, output, behavioral note, safety assurance, and feedback fallback. Every sentence adds value, though the feedback section is more meta-tooling. Still well-structured and not overly 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 tool's complexity (multiple config types, output schema exists), the description is complete: it covers what is scanned, checked, and not checked, parameter details, size limit, read-only nature, and a feedback mechanism. No gaps remain for agent selection or invocation.

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

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

Schema coverage is 100% with both parameters fully described in the schema. The description repeats these details (e.g., 'Required. 500 KB max.') but does not add new semantic 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 scans CI configs (GitHub Actions, Vercel, Netlify) for exposed secrets, missing lockfile enforcement, and unpinned dependencies. It distinguishes from sibling tools like frontend_security_audit_manifest by specifying the resource (CI configs) and checks performed.

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 when to use (user has CI config content), notes limited functionality for Vercel/Netlify (secrets only in Sprint 8), and clarifies that ${{ secrets/ env }} references are not flagged. It lacks explicit alternatives or when-not-to-use but offers a feedback fallback if results don'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?

The description goes beyond annotations by detailing the verdict criteria (BLOCK, CAUTION), data sources (OSV.dev, deps.dev, npm registry), and constraints (500 KB max). It clearly states the tool is read-only, has no side effects, and is idempotent, consistent with the annotations. No contradictions.

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

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

The description is detailed but efficiently structured: purpose first, then parameter details, then conditions, sources, and finally the feedback fallback. It is slightly long but every sentence adds value; no filler.

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

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

Given the tool's moderate complexity (2 parameters, no enums, rich annotations), the description covers all essential aspects: purpose, usage, behavioral details, parameter semantics, and even a feedback mechanism. An output schema exists but is not needed to explain return values as the description already summarizes 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?

Both parameters are described in the schema (100% coverage), but the description adds crucial context: 'manifest' is required with a 500 KB size limit, and 'lockfile' when provided audits pinned versions versus semver ranges. This enriches the agent's 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 clearly states it audits a frontend package.json for security risks and returns a SHIP/CAUTION/BLOCK verdict. It distinguishes from the sibling 'security_fetch_package_vulnerabilities' which audits a single package, making the tool's purpose and differentiation explicit.

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

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

The description provides explicit when-to-use guidance: it works on a full package.json, not a single package. It specifies that the 'lockfile' parameter is optional and explains the behavioral difference when provided vs absent. It also directs to call 'report_feedback' if the response is inadequate, offering a clear 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?

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds algorithm details (Damerau-Levenshtein distance ≤2, curated corpus) and output fields, ensuring full transparency.

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 and sibling differentiation. Every sentence adds value, but it is slightly verbose for a simple tool.

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

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

Given the tool's complexity, the description covers algorithm, scope, output schema, and fallback behavior. The existence of output schema does not detract from the comprehensive description.

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

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

Schema coverage is 100% with clear parameter descriptions. The description restates parameters with defaults and requirements but adds little 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 identifies the tool as typosquatting detection for the top 500 frontend packages, and explicitly distinguishes it from the sibling 'security_detect_typosquatting' for backend packages.

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

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

It provides explicit guidance on when to use this tool (frontend packages) and when to use the sibling (backend packages), mentions fewer false positives, and includes a fallback instruction for unsatisfactory results.

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 goes beyond annotations by clarifying the tool is read-only, idempotent, has no side effects, and lists data sources (OSV.dev, deps.dev, npm registry). Annotations already mark readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and the description confirms and adds 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 concise and well-structured. Each sentence adds value: purpose, scope, parameters, behavior, sources, and fallback. No redundancy or filler.

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

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

Given the tool's complexity (2 parameters, output schema present, rich annotations), the description fully covers purpose, usage, parameters, behavior, return content, and error handling via feedback. No missing elements.

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 extra meaning: notes that version is optional and resolves to latest if omitted, and calls package_name required. This clarifies behavior beyond the schema's parameter 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 provides a risk brief for npm packages with frontend-specific context, including specific signals (weekly_downloads, is_ui_component). It distinguishes from the generic security_fetch_package_risk_brief by specifying ecosystem scope.

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

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

Explicitly states when to use this tool (for npm packages with frontend context) and when to use the sibling (security_fetch_package_risk_brief for non-npm ecosystems). Also provides a fallback feedback mechanism 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?

Beyond annotations (readOnly, idempotent), it adds caching behavior (4-hour cache), data source transparency (SAM.gov + USASpending.gov), and encoding requirements for the keyword parameter. 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?

Well-structured with front-loaded purpose, parameter list, return fields, usage guidance, and fallback. Every sentence is informative without unnecessary verbosity.

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 (1 required param, 3 optional, output schema exists), the description covers all aspects: purpose, parameters, usage, caching, sources, and even a gap reporting mechanism. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds encoding guidance for the keyword parameter and clarifies defaults. It also explains the return fields, providing useful context 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?

The description clearly states the tool fetches currently open government contract solicitations by keyword. It distinguishes itself from the sibling tool govcon_search_contract_awards by specifying historical awards vs. open solicitations.

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

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

Provides explicit when-to-use ('when looking for active bid opportunities') and when-not-to-use ('use govcon_search_contract_awards instead when you need historical awards'), plus 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 declare readOnlyHint, destructiveHint false, idempotentHint true. Description adds further context: fuzzy matching, data source (USASpending.gov), 4-hour cache, and return fields. 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?

Well-structured with front-loaded purpose, parameter details, usage guidance, and caching info. Slightly lengthy but every sentence adds value; 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 output schema exists, description explains return fields and caching. Covers prerequisites, optional parameter, source verification, and error handling. Complete for a tool with 2 parameters.

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

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

Both parameters are described in schema (100% coverage). Description adds value: specifies vendor_name is required and uses fuzzy match, lists jurisdiction options with default US. 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?

Clearly states it fetches the complete federal contract award history for a specific vendor. Distinguishes from sibling tool govcon_search_contract_awards 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 describes when to use this tool (researching a specific company) and when to use the alternative (exploring without a specific vendor). Also provides fallback instructions 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?

Discloses return fields (award amounts, recipient vendors, NAICS codes, award dates) and cache duration (4-hour cache), adding value beyond annotations which already indicate read-only, idempotent, and open-world hints.

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

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

Concise yet comprehensive paragraph, front-loading the core purpose, with no redundant sentences; each sentence adds specific 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 all necessary aspects: purpose, parameters, alternatives, data source, caching, and expected return fields, making it fully self-contained for an agent.

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

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

Schema coverage is 100% with good descriptions, but the description adds real-world examples and clarifies parameter usage (e.g., 'keyword: Contract scope e.g. 'cybersecurity software''), enhancing 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 verb 'search' and resource 'government contract awards', and distinguishes from siblings by explicitly naming alternative tools for different use cases.

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 on when to use this tool vs alternatives ('Use govcon_fetch_vendor_contract_history...', 'Use govcon_fetch_open_solicitations...') and mentions data source and cache behavior.

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 reinforces annotations with statements like 'Read-only. No side effects. Idempotent.' and adds valuable behavioral context such as 'Fuzzy match — common names may return many results' and '24-hour cache'. This goes beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose. It includes all necessary information without redundancy, though it is slightly lengthy due to the added parameter details and feedback instruction. Very 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?

For a tool with 2 parameters and an output schema, the description covers purpose, usage, behavioral traits (fuzzy match, cache, source), and even includes a fallback to report_feedback. It is fully complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the fuzzy match warning for inventor_name, which provides critical behavioral context beyond the schema description. This additional information justifies a score of 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 'Fetch the patent portfolio for a named inventor with optional assignee filter', specifying a distinct verb and resource. It also differentiates from the sibling tool legal_search_patents_by_keyword, making it easy for an AI agent to select the correct tool.

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

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

Explicit usage guidance is provided: 'Use this when researching an inventor's work or a company's patent portfolio. Use legal_search_patents_by_keyword instead when you need patents by topic not by inventor.' This clearly tells the agent when to use this tool and when to choose an alternative.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by stating 'Read-only. No side effects. Idempotent.', and further discloses automatic normalization, 24-hour cache, and verified source (EPO OPS). 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?

Approximately 130 words, front-loaded with purpose. Every sentence adds value: action, read-only, parameter examples, normalization, output fields, usage guidance, caching, and feedback fallback. No superfluous content.

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

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

Given the tool's simplicity (2 params, output schema present), the description is complete: it covers input format, behavior, output summary, caching, alternative tools, and a fallback mechanism. The output schema already describes return structure, so the summary 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%, but the description enriches parameter semantics with examples (e.g., EP1000000, CN120586032), clarifies jurisdiction default and optional nature, and explains normalization behavior. This goes 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?

The description explicitly states the verb 'fetch' and resource 'patent details by patent number and jurisdiction'. It distinguishes itself from sibling tools like legal_search_patents_by_keyword and legal_fetch_patent_citations by specifying the use case 'when you have 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 provides clear when-to-use guidance: 'Use this when you have a specific patent number. Use legal_search_patents_by_keyword instead when you only have keywords.' It also mentions the optional jurisdiction hint and includes a fallback instruction to report feedback if needed.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by stating the source (EPO OPS), cache duration (24-hour), normalization behavior, and return structure (citing and cited patents with filing dates and titles). 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 clear sections: purpose, parameter details, use-case, alternative, source, cache, and fallback. Every sentence adds value, but it is somewhat verbose; slight trimming could improve conciseness.

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

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

Given the tool's moderate complexity (2 params, output schema exists), the description is highly complete: it covers input formats, normalization, return structure, use-case, alternative, source reliability, cache policy, and a 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% with descriptions for both parameters. The description adds helpful examples for patent_number (EP1000000, CN120586032, etc.) and clarifies jurisdiction defaults and normalization behavior, going 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 fetches forward and backward citation chains for a specific patent, using a specific verb and resource. It distinguishes from the sibling tool legal_search_patents_by_keyword by specifying the use case of prior art citation chains vs topic search.

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

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

The description provides explicit when-to-use: 'Use this when building a prior art citation chain for a specific patent you already have.' It also gives an alternative tool (legal_search_patents_by_keyword) and includes a fallback mechanism via report_feedback if the response 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 and idempotentHint. The description adds details like 'Returns up to 10 matches,' '24-hour cache,' and 'Verified source: EPO OPS + USPTO.' Also includes the 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 a single paragraph but well-organized, starting with purpose, then parameters, usage guidance, and additional notes. Every sentence adds essential information without redundancy.

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

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

Given 3 parameters (all documented), an output schema exists, and the description covers return fields, limits, cache, source, and feedback. It fully addresses the needs for a search 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 covers 100% of parameters with descriptions. The description adds value with examples (e.g., 'neural network image classification' for keywords, ISO 8601 format for date_from) and clarifies defaults and options (EP default for jurisdiction).

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

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

The description clearly states 'Search patents by keyword across EPO, USPTO, or WIPO.' It specifies a specific verb and resource, and distinguishes from the sibling tool legal_fetch_patent_by_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?

Explicitly says 'Use this when finding prior art or exploring a technology landscape without a specific number. Use legal_fetch_patent_by_number instead when you have the patent number already.' Also notes read-only, idempotent, no side effects.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description reinforces these with 'Read-only. No side effects. Idempotent.' and adds valuable context: 'UK only,' 'Verified source: UK Charity Commission OGL v3,' 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, starting with the core purpose, then listing key attributes, usage guidelines, and return values. Every sentence provides essential information without redundancy. It is concise yet comprehensive.

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

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

Given the output schema exists, the description appropriately summarizes key return fields (registration status, income, etc.). It also covers caching, source verification, and provides a feedback mechanism, making it fully self-contained for an agent to use correctly.

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

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

The input schema already documents the parameter, but the description adds format details ('7 digits, e.g. 1234567 or full/partial organisation name') and clarifies that it's required. This enhances understanding 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 specifies the action ('Fetch'), the resource ('UK registered charity details'), and the input criteria (charity number or name). It explicitly distinguishes this tool from sibling tools for US nonprofits, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (UK charities only) and when to use alternatives ('nonprofit_fetch_nonprofit_by_ein' or 'nonprofit_search_nonprofits_by_name' for US nonprofits). It also includes instructions for reporting gaps, ensuring proper usage.

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 explicitly states 'Read-only. No side effects. Idempotent.' Matches annotations (readOnlyHint, destructiveHint, idempotentHint). Also mentions caching behavior (7-day 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?

Very concise yet comprehensive. Front-loaded with key purpose and behavioral traits. Every sentence adds value, including the feedback mechanism call-to-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 tool has a single parameter, comprehensive annotations, and presumably an output schema (not shown but mentioned), the description is complete. It even includes a fallback feedback instruction.

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

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

Schema coverage is 100% for the single parameter ein. Description adds format examples and emphasizes it's required, which improves usability beyond the schema description.

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

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

The description explicitly states the tool fetches IRS 990 filing data for a US nonprofit by EIN. It specifies the return data (name, revenue, expenses, etc.) and distinguishes from the sibling tool nonprofit_search_nonprofits_by_name.

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

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

Provides clear guidance: use this when you have the exact EIN, use nonprofit_search_nonprofits_by_name when you only have a name. Also includes EIN format examples.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint as true, establishing safety and idempotency. The description adds valuable behavioral context beyond annotations: rate limit of 30/minute, no authentication required, and the feedback mechanism. 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 somewhat long but well-structured: it front-loads the main purpose, then details outputs, parameters, constraints, and relations. Every sentence adds value, and the flow is logical. It is not overly concise but avoids 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 (indicated but not shown), the description covers all essential aspects: main purpose, key outputs, parameter constraints, rate limit, auth, sibling relation, and error handling. Annotations are rich, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters (ein and years). The description restates the years range and default, and provides an example EIN format, but does not add significant new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a 5-year financial trend for US nonprofits, listing specific outputs like trend_direction, CAGR, and year-by-year trends. It distinguishes itself from the sibling nonprofit_fetch_nonprofit_full_profile by explicitly mentioning that it adds multi-year context, fulfilling the requirement of a specific verb+resource with sibling differentiation.

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

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

The description provides explicit guidance on when to use this tool (for multi-year context) and names the alternative (nonprofit_fetch_nonprofit_full_profile). It also includes a fallback instruction to call report_feedback if the response does not serve the user's need, which is excellent usage guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds significant behavioral details: data refreshed on each call, rate limit 30/minute, no auth required, API sources and fallback, and explicit output components. This goes beyond what annotations provide.

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

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

The description is fairly long but well-structured, front-loading the main purpose and outputs. Every sentence adds value, 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 tool complexity and the existence of an output schema, the description covers usage, behavior, output components, target audience, and error handling via report_feedback. It is comprehensive for due diligence 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% and the schema already describes the ein parameter with format example. The description does not add extra meaning beyond what is in the schema.

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

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

The description clearly states the tool performs 'complete nonprofit due diligence' and lists specific outputs like revenue trends, executive pay, risk flags, and health score. It distinguishes from sibling tools like nonprofit_fetch_nonprofit_by_ein and nonprofit_fetch_nonprofit_financial_trends by emphasizing 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 specifies target users (grant-makers, investors, compliance teams) and mentions reporting gaps via report_feedback. However, it does not explicitly tell when not to use this tool versus alternatives like the basic EIN lookup or financial trends 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?

Discloses rate limit ('30/minute'), no authentication required, and NTEE code mapping beyond annotations. Annotations already indicate read-only, idempotent, non-destructive, open-world; description adds non-contradictory behavioral details.

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 somewhat long but every sentence provides value. Information is front-loaded with primary purpose and output. Slightly verbose but not excessive.

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?

Output schema exists so description need not explain return format. Description covers return size (up to 25 results), specific fields (revenue, assets, health scores), rate limits, auth, and next steps. Complete for a search 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?

Adds meaning beyond schema: category maps to specific NTEE categories and accepts raw NTEE letters. State parameter is explained as US state code. Schema coverage is 100% but description enhances understanding.

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

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

Clearly states 'Search US nonprofits by mission category and state' with specific verbs and resources. Distinguishes from sibling tools like nonprofit_search_nonprofits_by_name and nonprofit_fetch_nonprofit_full_profile by mentioning follow-up usage.

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

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

Explicitly provides usage context: 'Starting point for nonprofit due diligence — follow with nonprofit_fetch_nonprofit_full_profile for deep dive.' Also includes fallback instructions to call report_feedback if the tool doesn't meet the need.

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

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

Discloses read-only, no side effects, idempotent behavior, US-only scope, up to 25 results, 7-day cache, and verified IRS source. Adds value beyond annotations by providing concrete limits and source details.

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 concise yet comprehensive, front-loaded with purpose, then behavioral notes, parameter details, usage guidance, and fallback. Each sentence adds value 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?

Covers purpose, behavior, parameters, usage, source, caching, and feedback. Given presence of output schema and annotations, the description is fully complete for an agent to correctly 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?

Schema coverage is 100%, so baseline is 3. Description adds context like 'Full or partial' for name and 'defaults to all states' for state, enhancing understanding beyond raw 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 searches US nonprofits by name with an optional state filter, using specific verbs and resource. It distinguishes from sibling tool nonprofit_fetch_nonprofit_by_ein, providing 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 states when to use this tool (when you have a name but not EIN) and when to use the sibling tool (having exact EIN). Also provides a feedback fallback mechanism for unsatisfactory results.

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.' and mentions timeout (30 seconds), cache (4-hour), and fallback to Federal Register, going beyond the annotations which already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

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 and concise; starts with main action, then key properties, usage guidance, and additional details. Every sentence adds value. 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 output schema exists and annotations cover safety, the description is thorough: lists return fields, mentions cache, timeout, fallback, and includes feedback mechanism for 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?

Only one parameter docket_id with schema description. Tool description adds examples and format clarification ('e.g. EPA-HQ-OAR-2021-0317 or FTC-2024-0041'). Schema coverage is 100%, baseline 3, with enhancement.

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 full details for a specific regulatory docket by ID' with a specific verb and resource. It differentiates from sibling tool regulatory_search_open_rulemakings 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 says 'Use this when you have a docket ID from a search' and 'Use regulatory_search_open_rulemakings instead when you need to find dockets by topic first.' 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 already declare readOnlyHint, destructiveHint, and idempotentHint; the description reinforces these and adds further context: 'US federal only', 'Verified source: Federal Register API', and '4-hour cache'. This adds value beyond annotations without any 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 a single paragraph but is densely packed with useful information. It is front-loaded with the core purpose and usage, and every sentence adds value. While it could benefit from structural elements like bullet points, it remains concise and 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 (which likely covers return values), the description adequately explains the tool's purpose, parameters, output structure (document type, title, etc.), caching, and source. Minor details like pagination are not mentioned, but overall it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., 'SEC, Food and Drug Administration'), default behaviors ('defaults to all notices', 'defaults to last 90 days'), and format details (ISO 8601) that are not fully covered in the 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?

The description uses a specific verb ('Fetch') and resource ('Federal Register notices and rules'), and clearly states the scope ('for a specific agency'). It also distinguishes itself from a sibling tool by explicitly mentioning when to use an alternative for topic filtering across all agencies.

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 ('monitor recent regulatory activity for an agency') and provides a clear alternative ('Use regulatory_search_open_rulemakings instead when filtering by topic across all agencies'). It also gives instructions for handling insufficient responses by calling 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, destructiveHint, idempotentHint, and openWorldHint. The description adds useful behavioral context: 'US federal only', '4-hour cache', 'Verified source', and a feedback mechanism if results are unsatisfactory. Some redundancy with annotations but still adds value.

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 with front-loaded purpose, parameter list, usage guidance, and feedback mechanism. Some redundancy (e.g., 'Read-only. No side effects. Idempotent.' repeated from annotations) but overall concise and 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?

With an output schema present, the description appropriately summarizes return fields (title, agency, comment deadline, etc.). It also addresses error handling via report_feedback. Covers all necessary context for a simple query tool.

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

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

Schema coverage is 100%; the description repeats parameter info found in the schema (keyword required, agency optional, status optional with default) but adds no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the action ('Search open rulemakings and public comment periods'), specifies the resource (Regulations.gov and Federal Register), and distinguishes from a sibling tool (regulatory_fetch_docket_details) 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 advises when to use this tool ('when monitoring regulatory activity on a topic') and when to use an alternative ('when you have a docket ID and need full detail'). Also notes caching and source verification.

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 states the tool creates a report (a write operation), but annotations declare `readOnlyHint: true`, which implies no side effects. This is a direct contradiction. The description also does not clarify behavioral traits like side effects, data persistence, or response expectations beyond the 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 informative but somewhat verbose. It includes parameter descriptions in a list format and an example, which helps structure. However, it could be more concise, as some points are redundant with the schema.

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

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

Given the tool has 8 parameters, 3 required, and an output schema, the description covers basic usage but lacks important context due to the annotation contradiction. It does not explain return values or confirm whether the tool is idempotent, leaving gaps in completeness.

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

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

Schema description coverage is 100%, so the description adds some value by providing an example and clarifying the use of `feedback_type` and `agent_gap`. However, it largely reiterates schema details without significant new meaning. Baseline is 3, and this meets it.

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

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

The description clearly states the tool's purpose: 'Report a data quality issue or agent intent gap for a DataNexus tool response.' It uses specific verbs and resources, and it distinguishes from sibling tools that perform other functions like data retrieval or API management.

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

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

The description provides a concrete example (`report_feedback(tool_id="T10", query_hash="abc123", signal="incorrect_data")`) that guides usage. It explains required and optional parameters, but does not explicitly state when not to use the tool or compare it to alternatives.

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

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

The description adds useful behavioral details beyond the annotations, listing the return values (status, message, tool_id, upgrade_url) and including an example call. This supplements the readOnlyHint and idempotentHint annotations well, though it could further clarify edge cases.

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, consisting of three short lines that front-load the main purpose, then succinctly describe the parameter and return values. Every sentence serves a clear function with no redundancy.

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

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

For a simple read-only tool with one parameter and an existing output schema (implied but not provided), the description is largely complete. It explains the purpose, parameter usage, and return fields, and includes an example. It does not cover error handling or corner cases, but given the simplicity, this is acceptable.

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

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

The input schema already provides full coverage (100%) for the single parameter 'tool_id' with a detailed description. The description repeats this information almost verbatim, adding no new semantic insight beyond the schema. Thus a baseline score of 3 is appropriate.

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

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

The description clearly and specifically states the tool's function: 'Check MCPize subscription status for a DataNexus tool.' It uses a precise verb-resource pair and distinguishes the tool from its many siblings (none of which perform this check).

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 when to use the tool by stating 'Pass the tool the user is asking about,' implying it should be used when a user inquires about a specific tool's subscription. It does not, however, explicitly list alternatives or counter-indications, which would elevate the score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds useful behavioral context beyond annotations, such as reducing context load from 40000 to 800 tokens and the open-world hint (no side effects confirmed). It also explains the tool's output (tool names and parameter hints) and provides fallback instructions. 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 relatively concise at about 120 words and well-structured: it begins with purpose, then parameter details, followed by usage instructions and fallback guidance. It is front-loaded with the key action. However, some parameter descriptions could be trimmed without losing clarity, preventing a perfect score.

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

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

Given the tool's complexity (2 parameters, many siblings, output schema present), the description covers all necessary aspects: purpose, when to use, when not to use, parameter explanations, expected output, and error handling (feedback). It also mentions that the tool reduces context load, which is a key operational detail. 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%, so the schema already documents both parameters. The description adds semantic value by explaining the query parameter's purpose ('Plain English description of your task, e.g. ...') and the domain parameter's restriction to specific sub-servers. It also contextualizes them within the usage flow (e.g., reducing context load). While baseline is 3 due to high schema coverage, the description's extra guidance warrants 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 the tool's purpose: 'Find the right DataNexus tool by describing your task in plain English.' It specifies it is read-only and has no side effects, and distinguishes it from siblings by instructing to call it before other tools and mentioning alternatives like validate_tool_output.

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

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

Explicit guidance is provided: 'Call this before any other DataNexus tool to reduce context load' and 'Do not call this recursively or to validate results — use validate_tool_output for that.' It also directs to report_feedback if the tool's response does not serve the user's need, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context: 'No auth required,' 'Rate limit: 60/minute,' 'Max 50 items,' and details about static vs. network-dependent paths. No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the main action. Every sentence adds value: purpose, input format, output, behavior notes (static vs network), limits, rate limit, auth, target audience, and fallback instruction. No wasted words; compact yet complete.

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 paths, multiple constraints), the description covers all necessary aspects: inputs, processing behavior, output nature, rate limits, concurrency, audience, and error handling via feedback. Although no output schema is provided, the description sufficiently describes the verdict format.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the two input paths: 'Input package names (with ecosystem) or SPDX IDs' and noting that the package path uses deps.dev while SPDX IDs use a static table. This clarifies the difference between the two optional parameter groups.

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: 'Audit the licence compatibility of your entire dependency list.' It specifies inputs (package names with ecosystem or SPDX IDs) and outputs (COMPATIBLE/CONFLICT verdict with conflicting pairs and recommended action). This distinguishes it from sibling tools like 'security_fetch_licence_analysis' which may focus on fetching rather than compatibility analysis.

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: 'For developers and compliance teams auditing open source licence risk before shipping.' It also gives performance hints (static SPDX table, deps.dev network calls, concurrency limit). However, it does not explicitly state when to use this tool over siblings, nor does it provide 'when not to use' guidance, though the fallback instruction partially addresses cases where the tool doesn't meet 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?

Beyond annotations (destructiveHint=true, openWorldHint=true), the description details persistent behavior (90-day TTL, Redis), input limits (500 KB), return signals (go_no_go, new_findings), and rate limits (10/min). No contradictions with annotations; adds significant value.

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 efficient, covering all essential aspects in a few sentences with no redundant phrases. Important details are front-loaded (persistent watch, formats), and secondary details follow logically.

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 (stateful watch, multiple actions, persistence), the description covers registration, checking, deregistration, formats, storage, limits, rate limits, auth, and error reporting. Output schema exists, so return values need not be detailed. Complete for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that sbom is required for register, watch_id is unique, and action has three values, but adds no new information beyond the schema's descriptions. Minimal added value.

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

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

The description clearly defines the tool as a persistent SBOM watch for continuous monitoring of CVEs, differentiating it from sibling one-off scanning tools like security_audit_sbom_vulnerabilities. Specific verbs like 'Register once, check anytime' and supported formats (CycloneDX, SPDX) make purpose unambiguous.

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

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

The description explicitly targets DevSecOps teams monitoring production dependencies and provides rate limits and auth requirements. While it doesn't formally exclude other uses, the context implies a specific niche. The fallback instruction for report_feedback guides when the tool fails to meet 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?

The description adds context beyond annotations: 1-hour cache, return structure, source (deps.dev). Annotations already declare readOnly and idempotent, but description enriches with operational details.

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 and well-structured but slightly verbose. Every sentence adds value, but could be tightened slightly for agent efficiency.

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 beyond what it provides. It covers source, cache, alternative tool, and policy defaults comprehensively.

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 description adds critical details: max SBOM size (500 KB), exact SPDX IDs for policy, default policy values, and behavior for unlisted licenses. All parameters are thoroughly explained.

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

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

The description clearly states the tool audits an SBOM against a license policy and returns a verdict (PASS/WARN/BLOCK). It also explicitly distinguishes from the sibling tool for CVE auditing.

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 security_audit_sbom_vulnerabilities for CVE auditing instead.' It also specifies default policy behavior and restrictions for policy parameters.

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

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

Annotations already declare readOnlyHint, destructiveHint false, idempotentHint, and openWorldHint. The description adds useful context: 'Large SBOMs (100+ packages) may take up to 10 seconds. Returns CVEs grouped by package with severity and fixed versions. Verified source: Google OSV.dev batch API. 1-hour cache.' This enhances transparency 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 concise and well-structured, with purpose, behavior, parameter, usage, and feedback all covered in a few efficient sentences. No wasted words.

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

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

Given the complexity of SBOM auditing, the description comprehensively covers purpose, usage, parameter format, performance caveats, return structure, source verification, caching, and fallback. Output schema exists, so no need to detail return types.

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

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

Schema coverage is 100% for the single parameter sbom_json. The description adds minimal value by specifying accepted formats (CycloneDX or SPDX), but largely repeats schema info. 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: 'Audit a Software Bill of Materials for known vulnerabilities across all listed packages.' It specifies the resource (SBOM) and action, and distinguishes from sibling security_fetch_package_vulnerabilities by noting the former is for full SBOMs.

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

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

Explicit usage guidance is provided: 'Use this when you have a full SBOM to audit. Use security_fetch_package_vulnerabilities instead when checking a single package version.' It also includes a fallback feedback mechanism for incomplete results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by disclosing no authentication required, a rate limit of 60/minute, cold-start fetch behavior (≤30s), and output information (similar_packages with anomaly scores and verdict). This contextualizes the tool's behavior 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 concise (5 sentences) and front-loaded with the core functionality. It includes essential details (distance algorithm, output, rate limit, auth, cold-start, and fallback) without redundancy. 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 and the presence of a full input schema, annotations, and output schema (not shown but noted), the description covers all necessary aspects: purpose, algorithm, inputs, outputs, performance, rate limit, auth, and even a guidance for reporting issues. It is complete for an AI agent to use correctly.

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

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

Input schema covers both parameters with descriptions and enum values, achieving 100% coverage. The description does not add parameter-specific details but provides algorithmic context (distance metric and package reference set). Baseline score of 3 is appropriate given the schema's completeness.

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

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

The description precisely states the tool's purpose: detecting typosquatting attacks against a package name using Damerau-Levenshtein distance. It clearly specifies the resource (package name) and the method (comparison against top-10,000 packages), distinguishing it from other sibling tools.

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

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

The description indicates the target audience (security engineers auditing supply-chain packages) and provides a fallback instruction for reporting if the tool doesn't serve the need. However, it does not explicitly exclude alternatives or specify when not to use this tool versus similar siblings.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description restates 'Read-only. No side effects. Idempotent' but adds useful context: 'CISA KEV catalog (updated daily, cached)' and describes output structure. 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, starting with purpose, then properties, usage guidance, and feedback. Every sentence adds value, though it could be slightly more concise. 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?

For a simple tool with one parameter, annotations, and output schema, the description covers input format, output fields, source, usage guidance, and error handling via report_feedback. Completely 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% with a clear description for cve_id. The description repeats the format but adds no new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check whether a CVE is in the CISA Known Exploited Vulnerabilities (KEV) catalog.' It specifies the resource, action, and 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?

Explicitly provides when to use (critical triage question not available in NVD) and alternatives: 'Use security_fetch_cve_detail for full CVE severity. Use security_fetch_cve_epss for exploit probability.' Also 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?

Beyond annotations (readOnlyHint, idempotentHint), the description confirms 'Read-only. No side effects. Idempotent.' and adds 'Verified source: NIST NVD. 1-hour cache.' This provides useful context about data freshness and reliability.

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: purpose, traits, parameter, usage guidance, source/cache, and fallback instruction. The structure is logical and concise, 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 simple tool (one parameter, output schema present), the description fully covers purpose, parameters, return fields, source, caching, and usage guidance. It also specifies when to use an alternative tool and how to report 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 input schema already has 100% coverage for the single parameter, including its format and required status. The description repeats this information without adding new semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Fetch' and resource 'full detail for a specific CVE by ID'. It also distinguishes from the sibling tool security_fetch_package_vulnerabilities, making the purpose unambiguous.

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

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

Explicitly states when to use ('when you have a CVE ID') and when not to ('use security_fetch_package_vulnerabilities instead'). Also provides fallback instructions for requesting feedback if the tool's output 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 non-destructive. Description adds caching behavior (6-hour cache), source (FIRST.org), and return format (epss and percentile). Provides valuable 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 well-structured: purpose, parameter, return values, thresholds, usage note, source, example. Front-loaded with the key action. Each sentence is necessary and no redundant content.

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

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

Tool is simple with one parameter and good annotations. Description covers all essential details: purpose, parameter format, return values, thresholds, caching, source, and guidance for integration with sibling tools. 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% for the single parameter cve_id. Description repeats the param definition and adds an example usage with the exact format, clarifying that quotes are needed. Baseline 3 plus example adds value.

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

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

Description clearly states it returns the EPSS exploit probability score for a CVE, predicting exploitation likelihood in the next 30 days. It distinguishes from sibling tools like security_fetch_cve_detail by explaining EPSS measures urgency while CVSS measures 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?

Provides explicit thresholds for action (patch immediately if >0.7, patch soon if 0.3-0.7, monitor if <0.3) and suggests using with security_fetch_cve_detail to prioritize patching. Does not explicitly state 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it is a parallel call, explains the meaning of UNKNOWN ('UNKNOWN means all upstream sources were unreachable — not that risk is low'), and notes rate limit (60/minute) and no auth required, all 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 that is information-dense but not overly long. It front-loads the purpose and includes necessary usage details. Slightly verbose with the report_feedback instruction, but that 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 has an output schema (not shown) and the description explains return values (verdicts and patch availability) and the meaning of UNKNOWN, it is complete for the complexity of the tool.

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

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

Schema coverage is 100% and the schema already explains cve_id with an example. The description adds no additional parameter semantics, so a baseline of 3 is appropriate.

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

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

The description clearly states 'Instant CVE risk verdict' and specifies it combines CVSS severity, CISA KEV exploitation status, and EPSS probability. It distinguishes itself from sibling tools like security_fetch_cve_detail or security_fetch_cve_epss by providing a composite verdict.

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

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

It explicitly states the tool is 'For security engineers triaging vulnerabilities after fetch_cve_watch fires' and provides a fallback instruction to call report_feedback if the result doesn't serve the user's need, with specific parameters.

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

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

The description provides extensive behavioral context beyond annotations: it explains persistence via Redis, daily background refresh from NVD, CISA KEV, EPSS, return structure (has_new_events, events, call_back_in), rate limit (60/min), and no auth. This complements the annotations (destructiveHint, readOnlyHint) 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 fairly concise for its content, front-loading the core purpose. Each sentence adds value, though it could be slightly trimmed (e.g., the repetition of 'create, check, delete'). The structure is logical: purpose, features, return info, rate limit, target user, fallback.

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 (3 params, all required, multiple actions, persistence), the description covers all necessary context: what it does, how it works (Redis, daily refresh), what it returns, rate limits, auth, and target audience. The presence of an output schema further reduces the need to detail return fields, though the description already mentions them.

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

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

The input schema covers 100% of parameters with clear descriptions. The tool description restates the actions and CVE IDs but does not add new semantic details beyond the schema. Therefore, it meets the baseline for high schema coverage.

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

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

The description clearly identifies the tool as a persistent CVE watchlist, specifying the verb 'create, check, delete' and the resource (CVE watchlist). It distinguishes from siblings by emphasizing persistence and periodic updates, and contrasts with one-off CVE queries.

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 tracking CVE exposure over time. It includes a fallback to report_feedback if the tool does not serve the need. However, it does not explicitly mention when to use this tool over siblings like security_fetch_cve_detail or security_fetch_cve_risk_summary.

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: Redis cursor, first call returns last 30 days, subsequent calls return newer events, no external API calls, instant response. Annotations already declare readOnly=true, etc., but 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?

The description is thorough but slightly verbose. However, it is well-structured with clear sentences and front-loads the main purpose. Each sentence adds value.

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