ContrastAPI

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

The description adds valuable context beyond annotations by specifying the return format ('Returns JSON with fields: asn, holder, prefixes_v4, prefixes_v6') and stating 'no authentication required' (which annotations don't cover). While annotations already declare readOnlyHint=true and destructiveHint=false, the description reinforces this with 'Read-only lookup' but doesn't contradict annotations.

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

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

The description is efficiently structured with three sentences that each serve distinct purposes: stating the tool's function, providing usage guidance, and describing behavioral details. There's no wasted verbiage, and key information is front-loaded.

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

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

Given the tool's moderate complexity, comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), 100% schema coverage, and presence of an output schema, the description provides complete contextual information. It covers purpose, usage differentiation, behavioral details, and return format without needing to explain parameters or output structure that's already documented elsewhere.

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

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

With 100% schema description coverage, the input schema already fully documents the single 'target' parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 for adequate coverage when 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 specific action ('look up'), resource ('Autonomous System Number for a domain or IP address'), and output details ('returning the AS number, organization name, and all announced IPv4/IPv6 prefixes'). It distinguishes from sibling tools by explicitly naming ip_lookup as an alternative for different intelligence needs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('to identify which network operator owns an IP range, or to understand the network infrastructure behind a domain') and when to use an alternative ('For detailed IP-level intelligence (ports, reputation), use ip_lookup instead'). This clearly differentiates it from sibling tools.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds that it returns 404 for nonexistent IDs and mentions rate limits (100/hr free, 1000/hr Pro), enhancing 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?

Single, well-structured paragraph that covers purpose, usage, error behavior, rate limits, and return format—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?

Description fully explains the tool's purpose, input, output structure, error behavior, and usage sequence, making it self-contained for an AI agent despite lacking an explicit output schema definition.

Complex tools with many parameters or behaviors need more documentation. 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 detailed description for case_study_id, including format pattern. The description reinforces the parameter but doesn't add significant new semantics beyond what the schema provides.

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

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

The description clearly states it looks up a MITRE ATLAS case study, a documented real-world AI/ML attack incident, and differentiates from related tools like atlas_case_study_search and atlas_technique_lookup.

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

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

Explicitly says 'Use this after atlas_technique_search to find which incidents have exercised a given technique' and suggests using atlas_technique_lookup for technique-level detail, providing clear when-to-use 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=true, destructiveHint=false. Description adds rate limits (100/hr Free, 1000/hr Pro) and mentions slim records with next_calls for pagination, which go 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?

The description is concise (3-4 sentences) with no fluff. It front-loads purpose, then usage, sibling pointer, rate limits, and return format. 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 3 optional params, output schema described, rate limits, and a drill-down sibling, the description covers all key aspects: what, when, how, limitations, and what to expect. 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 good descriptions. Description adds useful context: keyword is substring, case-insensitive, min 2 chars with examples; technique_id format is clarified. This adds value beyond schema.

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

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

The description clearly states it searches ATLAS case studies by keyword or technique, with specific verb and resource. It distinguishes from sibling tools like atlas_case_study_lookup (for drill-down) and atlas_technique_search (technique 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?

Explicitly says when to use: 'when the user has a technique in hand and wants to see incidents that exercised it, or when searching by attack-class keyword.' Also advises using atlas_case_study_lookup for full details, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying error conditions (404), rate limits, and the return structure, going beyond annotations 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 relatively compact given the amount of useful information. It front-loads the main purpose and then adds context. Could be slightly more concise, but overall efficient.

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

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

Given the presence of an output schema and comprehensive annotations, the description provides sufficient additional context: return fields, error handling, rate limits, and cross-reference hints. It covers all necessary aspects for correct invocation.

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

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

The input schema already provides a detailed description of the parameter 'technique_id', including format and examples. The description does not add new semantic information for the parameter beyond what the schema offers. With 100% schema coverage, baseline is 3.

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

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

The description clearly states the tool's function: looking up a MITRE ATLAS technique, specifying the AI/ML adversarial attack catalog. It differentiates from sibling tools like atlas_technique_search by focusing on lookup by ID. The resource and action are unambiguous.

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

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

Explicitly states when to use: 'when the user asks about AI/ML threats, LLM red-teaming, or adversarial ML.' Also provides context on bridging to D3FEND via attack_reference_id, and notes pricing limits (100/hr, 1000/hr) and error behavior (404 if ID not in catalog).

Agents often have multiple tools that could apply. Explicit usage 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 (readOnly, idempotent, not destructive) are complemented by description disclosing return structure including next_calls (pagination) and rate limits (100/hr Free, 1000/hr Pro). 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?

Concise, front-loaded with primary purpose, then usage guidance, rate limits, and return schema. Every sentence adds unique value without redundancy.

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

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

Given the rich output schema, the description still provides essential context: return format, cross-reference hints, and rate limits. Adequately covers complexities 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?

All 4 parameters have schema descriptions (100% coverage). The description adds value by explaining parameter behavior (substring match, tactic format, enum meanings) and response structure 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 searches the MITRE ATLAS catalog of AI/ML attack techniques by keyword, tactic, or maturity. Distinguishes from sibling tools like atlas_technique_lookup by advising drill-down for full details.

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

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

Provides explicit when-to-use guidance (e.g., threat-model questions) and directs to alternative tools for drill-down and cross-referencing with D3FEND. Also mentions rate limits for access context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond this: 'Read-only orchestrated lookup, no authentication required' clarifies the safety profile and authentication requirements. It also mentions 'combines...in a single call' and 'orchestrated lookup' which suggests internal coordination of multiple data sources, though it doesn't detail rate limits or specific constraints.

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

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

The description is efficiently structured with three sentences: first states the comprehensive functionality, second provides usage guidelines with alternatives, third clarifies behavioral aspects and return format. Every sentence adds value with zero waste, and key information is front-loaded.

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

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

Given the tool's complexity (combining multiple data sources), the description provides complete context: purpose, usage guidelines, behavioral transparency, and mentions the JSON return structure. With annotations covering safety properties and an output schema presumably documenting the return fields mentioned, the description provides adequate contextual information for agent decision-making.

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

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

Schema description coverage is 100% with the single 'domain' parameter fully documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3. The description does imply the tool operates on root domains but doesn't provide additional syntax guidance beyond the schema's example.

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

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

The description clearly states the tool performs a 'comprehensive domain audit' that 'combines a full domain report (DNS, WHOIS, SSL, subdomains, WAF, threat intel, risk score), live HTTP security headers, and technology stack fingerprinting.' This is a specific verb+resource combination that distinguishes it from sibling tools like dns_lookup, ssl_check, or tech_fingerprint which focus on single aspects.

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

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

The description explicitly states 'Use this when you want a complete picture of a target without making multiple requests' and provides an alternative: 'For investigations that need only one aspect (e.g. just DNS or just SSL), use the dedicated tool instead.' This gives clear when-to-use guidance and names alternatives among the sibling tools.

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

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

The description adds substantial behavior beyond annotations: honors robots.txt (403 on Disallow), respects Cache-Control, throttles per eTLD+1, and warns about _untrusted fields. Annotations indicate readOnly, idempotent, non-destructive, and the description aligns 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 dense but not overly long; it front-loads the main action and asset list, then covers ethical, technical, and return details. A slightly more structured format (e.g., bullet points) could improve scannability, but every sentence is informative.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers all necessary context: expected inputs, ethical constraints, rate limits, pricing, error responses, and field trust warnings. It is 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 single parameter 'domain' is well-documented in the description with format constraints: 'Registrable domain... No scheme, no path, no port.' The schema description is also present, but the description adds deployment details (HTTPS fallback) and examples, enhancing clarity.

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

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

The description clearly states the tool's action: 'Scrape a domain's homepage <head> for public brand assets.' It lists specific assets (favicon, og:image, etc.) and distinguishes itself from siblings by focusing solely on homepage brand asset extraction, not crawling or other lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use cases are provided: 'enrich CRM records, build company-card UIs, or correlate a lead's site to their visual identity.' It also states what not to do: 'Strictly homepage-only (path /); we do NOT crawl.' However, it does not directly contrast with sibling tools, though the unique functionality 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 indicate safe, read-only behavior. Description adds valuable behavioral details: parent-tactics inheritance, per-item next_calls, and response 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?

Front-loaded with purpose, but description is somewhat verbose with detailed per-item call logic. Could be tightened without losing key 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?

Fully describes return structure, explains next_calls integration, and situates among sibling tools. With output schema present, all needed info is provided.

Complex tools with many parameters or behaviors need more documentation. 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 parameter with clear description. Description adds context on format, case-insensitivity, dedup, and rate limit counting, going beyond schema.

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

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

Description clearly states the tool performs bulk retrieval of MITRE ATLAS techniques, up to 50 per request, and contrasts with single-lookup sibling atlas_technique_lookup.

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

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

Explicitly positions as follow-up to atlas_case_study_lookup and mentions direct passing of techniques_used array. Includes rate limit tiers but doesn't explicitly exclude single-lookup use cases.

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

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

Annotations already indicate it's read-only, non-destructive, idempotent, and open-world, but the description adds valuable context: it specifies rate limits ('free tier allows 10 IDs per request, Pro allows 50') and clarifies it's a 'database lookup'. This enhances understanding beyond the annotations, though it doesn't detail error handling or latency.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines and behavioral details. Every sentence adds value—efficiency benefits, sibling comparison, return structure, and operational limits—with no wasted words, making it highly concise and well-structured.

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

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

Given the tool's complexity (batch lookup with rate limits), rich annotations, and the presence of an output schema, the description is complete. It covers purpose, usage, behavioral context, and output fields, providing all necessary information for an agent to use the tool effectively without redundancy.

Complex tools with many parameters or behaviors need more documentation. 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% description coverage, fully documenting the 'cve_ids' parameter. The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 without compensating for any gaps.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('Look up multiple CVEs') and resource ('CVEs'), distinguishing it from the sibling 'cve_lookup' tool. It explicitly mentions the efficiency benefit for batch operations, making the purpose distinct and well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 have a list of 5+ CVEs to check') and when to use the alternative ('For a single CVE, use cve_lookup'). It also mentions specific use cases like vulnerability scanning and dependency audits, giving clear context for application.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it specifies the threat feeds queried (ThreatFox, URLhaus, Feodo), mentions parallel querying, indicates tier-based rate limits (10/50 indicators), and describes timeout behavior ('partial (true if some indicators hit the overall timeout)'). No contradiction with annotations exists.

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

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

The description is efficiently structured and front-loaded: the first sentence states the core functionality, followed by usage guidelines, sibling tool reference, and output details. Every sentence adds value without redundancy, and it avoids unnecessary elaboration while covering all essential aspects.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (bulk operations, multiple threat feeds, tier limits) and the presence of rich annotations (readOnlyHint, openWorldHint, etc.) and an output schema (implied by 'Returns JSON with fields...'), the description is complete. It covers purpose, usage, behavioral traits, and output structure without needing to duplicate schema details, making it fully adequate for agent understanding.

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

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

The input schema has 100% description coverage, with the 'indicators' parameter fully documented in the schema (including examples, auto-detection, and tier limits). The description adds minimal additional parameter semantics beyond the schema, mainly reinforcing the auto-detection and tier limits. This meets the baseline score of 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose with specific verbs ('enrich multiple Indicators of Compromise', 'auto-detects each indicator type', 'queries threat feeds in parallel') and distinguishes it from its sibling tool ioc_lookup. It explicitly mentions the resource (threat feeds: ThreatFox, URLhaus, Feodo) and scope (multiple indicators in a single request).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 SOC alert triage, threat hunting, or batch enrichment when you have many suspicious indicators') and when not to ('For a single indicator, use ioc_lookup'). It also mentions tier-based limits (free: 10 indicators, Pro: 50), giving clear context for usage decisions.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive traits. The description adds valuable context beyond annotations: it specifies rate limits ('Maximum 10 per request for free tier, 50 for Pro'), clarifies authentication ('no authentication required'), and details the return format, enhancing behavioral 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 well-structured and front-loaded, with each sentence serving a distinct purpose: stating the tool's function, providing usage context, naming alternatives, detailing output, and adding behavioral notes. There is no wasted text, making it highly efficient.

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

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

Given the tool's complexity, rich annotations, and the presence of an output schema, the description is complete. It covers purpose, usage guidelines, behavioral context, and output details without redundancy, providing all necessary information for effective tool selection and invocation.

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

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

Schema description coverage is 100%, so the schema fully documents the 'packages' parameter. The description adds minimal extra semantics (e.g., examples of file types like requirements.txt), but doesn't provide significant additional meaning beyond what the schema already covers, aligning with the baseline for high coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('audit', 'scan') and resources ('project dependencies', 'requirements.txt, package.json, pom.xml, or Gemfile.lock'), and distinguishes it from siblings by explicitly naming alternatives (cve_lookup, cve_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 guidance on when to use this tool ('when you want to check many packages at once') and when to use alternatives ('For a single vulnerability by ID, use cve_lookup. For searching CVEs by product without version, use cve_search'), offering clear context and exclusions.

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

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

The description adds valuable behavioral context beyond what annotations provide. While annotations indicate read-only, open-world, idempotent, and non-destructive operations, the description explicitly states 'Read-only validation, no external requests made' and clarifies that it 'checks against security best practices.' This provides important implementation details about the validation approach and lack of network calls.

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

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

The description is efficiently structured with zero wasted sentences. It front-loads the core purpose, distinguishes from siblings, explains use cases, describes output format, and clarifies behavioral constraints — all in a compact paragraph where 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 (security header validation), the description provides complete context. With annotations covering safety aspects, an output schema presumably detailing the JSON response structure, and the description explaining the validation scope, use cases, and behavioral constraints, an AI agent has all necessary information to correctly 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?

With 100% schema description coverage, the input schema already fully documents the single 'headers' parameter. The description doesn't add significant parameter semantics beyond what's in the schema, though it does provide context about the headers being 'copied from browser DevTools, a curl response, or an existing configuration' which offers usage examples. This 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 states the tool's purpose: 'Validate a set of HTTP security headers that you already have' and specifies the exact headers checked (Content-Security-Policy, Strict-Transport-Security, etc.). It explicitly distinguishes this tool from its sibling 'scan_headers' by noting this analyzes provided headers while scan_headers fetches them live from a domain.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Unlike scan_headers (which fetches headers live from a domain), this tool analyzes headers you provide directly — useful for testing configurations before deployment or validating headers from non-public servers.' This clearly defines the appropriate context and names the specific alternative tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context beyond annotations: it specifies that the tool 'does not access any files, execute any code, or modify system state,' which clarifies the read-only nature in practical terms. It also mentions 'Uses language-specific patterns to detect unsafe data flow,' providing insight into the analysis method. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, followed by behavioral details, sibling differentiation, and output format. Every sentence earns its place: the first defines the tool, the second adds behavioral context, the third differentiates from siblings, and the fourth describes returns. No wasted words, and structure is logical.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (static analysis with multiple vulnerability types), the description is complete. Annotations cover safety and idempotency, the output schema exists (so return values need not be detailed in description), and the description adds necessary context like analysis method and limitations. It adequately complements structured fields without redundancy.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (code and language). The description adds minimal parameter semantics beyond the schema: it mentions 'source code snippets' for the code parameter and implies language context with 'language-specific patterns,' but these are largely redundant with schema descriptions. Baseline 3 is appropriate as the 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's purpose: 'scans source code snippets for injection vulnerabilities' with specific examples (SQL injection, command injection, path traversal). It distinguishes from sibling check_secrets by specifying 'For hardcoded key detection, use check_secrets.' The verb 'scans' and resource 'source code snippets' are specific and unambiguous.

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

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

Explicit guidance is provided on when to use alternatives: 'For hardcoded key detection, use check_secrets.' The description also clarifies the tool's scope by stating it performs 'read-only analysis on the provided code string' and does not access files, execute code, or modify system state, helping differentiate it from potentially destructive tools.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it specifies that analysis is performed in-memory without storage, uses pattern matching with language-specific context to reduce false positives, and clarifies the tool's limitations (no file/environment/system access). No contradictions with annotations exist.

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

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

The description is efficiently structured with zero wasted sentences: it states the purpose, explains behavioral context, provides usage guidance, and describes the return format. Each sentence adds clear value and is front-loaded with essential information.

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

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

Given the tool's complexity (static analysis with language context), rich annotations (covering safety and behavior), and the presence of an output schema (which handles return value documentation), the description provides complete contextual information. It covers purpose, usage, behavioral traits, and output structure without redundancy.

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

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

With 100% schema description coverage, the input schema fully documents both parameters. The description does not add any parameter-specific semantics beyond what the schema provides, so it meets the baseline of 3 without compensating for gaps.

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

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

The description clearly states the tool's purpose with specific verbs ('scans source code snippets for hardcoded tokens and keys') and resources ('AWS access keys, API tokens, connection strings'), and distinguishes it from sibling tool 'check_injection' for injection vulnerability detection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 on when to use this tool (for secret detection in code snippets) versus alternatives ('For injection vulnerability detection, use check_injection'), and it clarifies what it does not do (no file access, environment variable access, or system resource access).

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

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

The description adds valuable behavioral context beyond what annotations provide. While annotations indicate this is a read-only, open-world, idempotent, non-destructive operation, the description explains the unique value proposition: these are 'early-warning vulnerabilities' that ContrastAPI has indexed before NVD publication. It also specifies the return format and includes details about the 'sources' and 'first_seen_source' fields, which aren't covered by annotations.

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

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

The description is efficiently structured with three sentences that each serve a distinct purpose: stating the tool's unique function, explaining when to use it, and describing the return format. There's no wasted text, and the most important information (what makes this tool different) comes first.

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

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

Given that this tool has comprehensive annotations, 100% schema coverage, and an output schema exists, the description provides excellent contextual completeness. It explains the tool's unique value proposition, when to use it, and the return format, which is exactly what's needed beyond the structured data.

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

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

With 100% schema description coverage, the input schema already fully documents both parameters (limit and offset). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation but doesn't provide additional parameter semantics.

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

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

The description explicitly states the tool's purpose: 'List CVEs that ContrastAPI indexed from MITRE/GHSA BEFORE NVD has published them.' It clearly distinguishes this from sibling tools by specifying it returns early-warning vulnerabilities that other tools miss, differentiating it from cve_search and cve_lookup which likely return standard CVE data.

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

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

The description provides explicit guidance on when to use this tool: 'Use this to find the freshest, most actionable CVEs that other tools miss.' It clearly positions this as the tool for discovering vulnerabilities before they appear in NVD, creating a clear alternative to standard CVE search tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations: 'no authentication required' (auth needs) and 'Read-only database lookup' (reinforces safety). It doesn't contradict annotations and provides additional operational 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?

Front-loaded with purpose, followed by usage guidelines, return format, and behavioral notes. Every sentence adds value: first defines scope, second provides usage rules, third specifies output, fourth gives operational context. 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 tool has annotations covering safety (readOnly, non-destructive), an output schema exists (so return values don't need description explanation), and 100% schema coverage, the description provides complete context: clear purpose, usage differentiation, output field overview, and authentication/behavioral notes.

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

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

Schema description coverage is 100%, with the parameter cve_id fully documented in the schema (including format examples). The description doesn't add any parameter-specific information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Retrieve detailed information') and resource ('about a specific CVE vulnerability'), with explicit listing of the information retrieved (description, CVSS scores, EPSS, etc.). It distinguishes from siblings by naming cve_search and exploit_lookup as alternatives 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?

Explicitly states when to use ('when you have a specific CVE ID and need full details') and when not to use (directing to cve_search for product/severity searches and exploit_lookup for exploit finding). Provides clear alternatives with specific tool names.

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

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

The description adds valuable behavioral context beyond annotations: it specifies that results are sorted by publication date (newest first), discloses that no authentication is required, and describes the return format. While annotations already cover read-only, non-destructive, and idempotent properties, the description provides additional operational details that help the agent understand how the tool behaves.

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

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

The description is efficiently structured with three sentences: first states purpose and filters, second provides usage examples and alternative tool, third describes return format and behavioral details. Every sentence adds value with zero wasted words, and key information is front-loaded.

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

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

Given the comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), 100% schema coverage, and existence of an output schema, the description provides excellent contextual completeness. It covers purpose, usage guidelines, behavioral details, and return format, making it fully sufficient for an agent to understand and use this tool correctly.

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

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

With 100% schema description coverage, the input schema already documents all 4 parameters thoroughly. The description mentions filters on product name, severity level, and publication date range, which aligns with the schema but doesn't add significant semantic value beyond what's already in the parameter descriptions. This 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 states the tool searches the CVE database for vulnerabilities matching specific filters (product name, severity level, publication date range). It distinguishes from sibling cve_lookup by specifying this is for searching with filters rather than looking up a specific known CVE.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('to find recent vulnerabilities affecting specific software, or to get an overview of critical CVEs in a time window') and when to use an alternative ('For details on a specific CVE you already know, use cve_lookup instead'). This provides clear guidance on tool selection.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: rate limits (100/hr free, 1000/hr Pro), the lower bound caveat for cve_count, and the 404 response for missing CWEs. No contradictions with annotations.

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

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

The description is comprehensive and well-structured, with front-loaded purpose and clear separation of return fields, usage guidance, and rate limits. While slightly lengthy, every sentence adds value and there is 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 output schema exists and annotations provide safety guarantees, the description is exceptionally complete. It covers return fields, error conditions, rate limits, and behavioral quirks (cve_count lower bound), leaving no gaps for the agent.

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

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

The schema already has 100% coverage for the single parameter cwe_id with a description. The tool description enriches it further by listing accepted formats ('CWE-79', 'cwe-79', bare '79') and providing common examples (XSS, SQL injection, etc.), adding clear value.

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

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

The description clearly states the tool looks up MITRE CWE catalog records from research view 1000, specifying the return fields. It explicitly differentiates from siblings by describing its role in a workflow: 'Use after cve_lookup or kev_detail' and 'chain with cve_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 usage guidance, including when to use it (after cve_lookup or kev_detail), how to chain it with cve_search, and what error to expect (404 when not in research view). This helps the agent select the appropriate 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?

Beyond annotations (readOnly, idempotent, etc.), the description adds that extra entries beyond 500 are dropped server-side, explains the return structure, and notes rate limits per subscription. This provides practical behavioral context.

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

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

Four sentences efficiently cover purpose, usage, output fields, and limits. Minor repetition (explaining defended/undefended subsets) but overall compact and front-loaded with the key function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 it's a batch tool with multiple output fields, the description lists all return keys and includes rate limits. The output schema exists but is not in this context; description sufficiently informs an agent of what to expect.

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

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

Schema coverage is 100% with a detailed description including maxItems and examples. The description restates the cap but adds no new parameter meaning beyond what the schema already provides, so baseline score of 3 applies.

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

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

The description clearly states it performs a batch coverage breakdown of ATT&CK T-codes against D3FEND defenses, returning counts per tactic and identifying undefended techniques. This distinctively differs from sibling tools like d3fend_defense_for_attack (single technique) or d3fend_defense_lookup (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?

Explicitly advises use for assessing an entire attack campaign or threat model in one call, and suggests pairing with cve_search for gaps. Rate limits per plan are mentioned. Does not explicitly state when not to use (e.g., for a single technique), but the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: returns 200 with empty defenses list (gap is a signal), rate limits (100/hr free, 1000/hr Pro), and detailed response structure. 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 concise with two main sentences plus rate limit and response structure details. It front-loads the core purpose. Every sentence adds value, but the rate limit info could be considered separate context.

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

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

Given the tool's simplicity (1 parameter, output schema available, annotations cover safety), the description provides complete context: usage pairing, rate limits, response behavior for missing mappings, and response fields. 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?

The input schema has 100% description coverage for its single parameter, including format and usage guidance. The description adds context about bridging from CVE/ATLAS findings, but does not add 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?

The description clearly states 'Reverse lookup: given an ATT&CK T-code, return ALL D3FEND defenses that mitigate it.' It specifies the verb 'return', the resource 'D3FEND defenses', and the input format, distinguishing it from sibling tools like d3fend_defense_lookup and d3fend_defense_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 explicitly says to pair with cve_lookup or atlas_technique_lookup output when they carry an ATT&CK id, providing clear context for when to use this tool. It also mentions the response behavior for no mapping, but does not list exclusions or alternatives explicitly.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specifics: returns 404 for missing slugs, rate limits (100/hr free, 1000/hr Pro), and response 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?

All sentences are informative and necessary. Begins with core purpose, then context, usage advice, error behavior, rate limits, and output fields. 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 single-parameter lookup tool with full schema and output schema, the description covers workflow integration, error cases, rate limits, and response structure. 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% with a detailed description for defense_id (slug format, examples). The tool description does not add new information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Look up a MITRE D3FEND defense technique') and specifies the resource (D3FEND). It distinguishes from siblings like d3fend_defense_search by noting it provides the full record after 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?

Explicitly advises to use after d3fend_defense_search for completeness, indicates the response includes ATT&CK T-codes, and mentions rate limits. This guides appropriate 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rate limits and return structure, which provides further behavioral context. No contradictions.

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

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

Description is concise and front-loaded with purpose. Somewhat dense as a single paragraph, but every sentence adds value. Could slightly benefit from bullet points or clearer separation, but still efficient.

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

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

Covers all aspects: purpose, parameters with examples, rate limits, return format, and link to sibling. With output schema present, the description still explains return values explicitly. Complete for a search tool with 4 optional parameters.

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

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

Schema coverage is 100%. Description enriches parameters with examples for keyword ('token', 'hashing', 'sandbox') and artifact ('Access Token', 'File', 'Process'), explains tactic enum, and even gives an example query. This adds meaning beyond schema.

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

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

Clearly states 'Search the MITRE D3FEND catalog of defensive techniques by keyword, tactic, or targeted artifact.' Provides specific verb and resource, and distinguishes from sibling d3fend_defense_lookup by mentioning drilling into it for ATT&CK mappings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Use to discover defenses applicable to a given threat model' with concrete example '(tactic=Harden + artifact='Access Token')'. Also indicates when to use sibling tool: 'Drill into d3fend_defense_lookup...' and includes rate limits (Free: 100/hr, Pro: 1000/hr).

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

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

The description adds valuable context beyond annotations: it specifies the return format ('JSON with a records array, each containing type, value, and TTL fields') and explicitly states 'no authentication required.' While annotations cover read-only, open-world, and idempotent hints, the description enhances understanding with output structure and authentication details, though it doesn't mention rate limits or other constraints.

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

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

The description is efficiently structured with three sentences: the first states the purpose, the second provides usage guidelines, and the third covers behavioral details. Each sentence adds clear value without redundancy, making it front-loaded and appropriately sized for the tool's complexity.

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

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

Given the tool's low complexity (1 parameter), rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), and the presence of an output schema, the description is complete. It covers purpose, usage, behavioral traits, and output format, leaving no significant gaps for an AI agent to understand 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?

With 100% schema description coverage, the input schema already fully documents the single 'domain' parameter. The description does not add any additional semantic information about parameters beyond what the schema provides, so it meets the baseline of 3 without compensating for gaps.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('Retrieve all DNS records') and resources involved ('A, AAAA, MX, NS, TXT, CNAME, and SOA record types'), distinguishing it from sibling tools like 'domain_report' which provides a broader security overview. It goes beyond a simple tautology by detailing the scope of DNS records retrieved.

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

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

The description explicitly provides when to use this tool ('inspect mail routing (MX), verify nameserver delegation (NS), check SPF/DMARC policies (TXT), or confirm IP resolution (A/AAAA)') and when not to ('For a broader security overview that includes DNS, use domain_report instead'). It names a specific alternative tool, offering clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds context by stating 'no authentication required' and specifying the return format (JSON with sections and numeric risk_score), which provides useful behavioral details 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?

Front-loaded with purpose, followed by usage guidelines and behavioral details. Every sentence adds value: first defines the tool, second provides usage context, third specifies output format and behavioral traits. 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 tool has annotations covering safety (readOnly, non-destructive), an output schema exists (so return values need not be explained in description), and the description provides clear purpose, usage guidelines, and additional context like authentication, it is complete for this complexity level.

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

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

Schema description coverage is 100% with one parameter 'domain' fully documented. The description does not add meaning beyond the schema, which already explains the domain format. Baseline 3 is appropriate when 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 verb 'retrieve' and resource 'comprehensive security report for a domain', specifying it combines DNS records, WHOIS registration, SSL/TLS certificate, subdomain discovery, threat reputation, and risk score. It distinguishes from siblings by being a broad overview tool versus dedicated tools like ssl_check or dns_lookup.

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

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

Explicitly states 'use this as the first step when investigating a domain' and 'for deeper analysis of a specific area, follow up with the dedicated tool (ssl_check, dns_lookup, etc.)', providing clear when-to-use guidance and naming 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?

While annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, the description adds valuable context: 'Read-only lookup against a local database of disposable domains, no authentication required.' This clarifies the data source (local database) and authentication requirements beyond what annotations provide, though it doesn't mention rate limits or performance characteristics.

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

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

The description is efficiently structured with three sentences that each serve distinct purposes: stating the tool's function, providing usage guidance, and describing behavioral characteristics. There's no redundant information, and key details are front-loaded.

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

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

Given the tool's simple single-parameter design, comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), and the presence of an output schema (implied by 'Returns JSON with fields'), the description provides complete contextual information. It covers purpose, usage, and behavioral context without needing to explain return values.

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

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

With 100% schema description coverage, the input schema already fully documents the single 'email' parameter. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing extra value.

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

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

The description clearly states the specific action ('Check whether an email address uses a known disposable or temporary email provider') and identifies the resource (email addresses). It distinguishes this tool from siblings like 'email_mx' or 'domain_report' by focusing specifically on disposable email detection rather than general email or domain 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 explicitly provides usage context: 'Use this for input validation to detect throwaway signups or to assess the legitimacy of a contact email.' This gives clear guidance on when to use this tool versus alternatives like general email validation or domain reputation checks.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: 'Read-only DNS queries, no authentication required' clarifies the operational behavior and access requirements. However, it doesn't mention rate limits or specific error conditions.

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

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

Front-loaded with purpose, followed by usage guidance and behavioral details. Every sentence adds value: first explains what it does, second explains when to use it, third describes output format, fourth clarifies operational behavior. 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 tool has comprehensive annotations, 100% schema coverage, and an output schema (implied by describing return fields), the description provides complete context. It covers purpose, usage, output structure, and behavioral details without needing to repeat structured 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 description coverage is 100% with a single well-documented parameter. The description doesn't add any parameter-specific information beyond what the schema provides, but the baseline is 3 when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('analyze email security configuration') and resources involved (MX records, SPF, DMARC, DKIM). It distinguishes from siblings by focusing on email-specific DNS analysis rather than general DNS lookup, domain reporting, or other security checks.

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

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

Explicitly states when to use this tool: 'to verify email authentication setup or assess phishing risk for a domain.' It distinguishes from alternatives by specifying the email security focus, unlike general DNS or domain tools in the sibling list.

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

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

Adds details beyond annotations: rate limits, role/free-provider classification logic, Gmail +tag stripping. No contradiction with annotations (all safe/read-only 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?

Compact yet informative, covering all important facets. Could be slightly shorter, but 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 all checks, limitations, rate limits, and output fields; complements the existing output schema. Complete for an agent to understand tool behavior and 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 already fully describes the 'email' parameter with coverage 100%. Description provides usage examples but does not add new semantic detail 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?

Clearly states it is a one-call email validation tool combining multiple checks. Differentiates from siblings like email_mx and email_disposable by noting it replaces 2-3 separate calls.

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

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

Explicitly gives use cases (before adding to contact list, sending, auditing) and explicitly states what it does not do (SMTP probing) with alternative services suggested.

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

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

The description adds valuable behavioral context beyond annotations: it specifies the data sources (GitHub Advisory Database and ExploitDB), clarifies that no authentication is required, and describes the return format and meaning of an empty result. While annotations cover read-only, open-world, and idempotent properties, the description enriches this with practical implementation 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 efficiently structured with three sentences: the first states the purpose, the second provides usage guidance, and the third details behavioral aspects and output. Every sentence adds essential information without redundancy, making it front-loaded and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, rich annotations (readOnlyHint, openWorldHint, idempotentHint), and the presence of an output schema, the description is complete. It covers purpose, usage, data sources, authentication, and output interpretation, leaving no significant gaps for an AI agent to understand 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?

With 100% schema description coverage, the input schema already fully documents the single required parameter 'cve_id' with format examples. The description does not add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing extra semantic value.

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

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

The description clearly states the specific action ('Search for publicly available exploits and proof-of-concept code') and target resource ('for a specific CVE'), distinguishing it from siblings like 'cve_lookup' which likely provides vulnerability details rather than exploit information. The verb 'search' is precise and the scope is well-defined.

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

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

The description explicitly states when to use this tool ('Use this after cve_lookup to assess whether a vulnerability has weaponized exploits in the wild') and provides context about its purpose ('which indicates higher real-world risk'). It differentiates from 'cve_lookup' by focusing on exploit assessment rather than vulnerability details.

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

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

The description adds valuable context beyond annotations: it specifies the database source (MalwareBazaar), mentions 'no authentication required' (though annotations imply safety, this clarifies access), and details return fields. However, it doesn't mention rate limits or potential errors, leaving some behavioral aspects uncovered.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines and behavioral details. Every sentence adds value—none are redundant or wasteful—making it efficiently structured and appropriately sized.

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

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

Given the tool's low complexity (1 parameter), rich annotations (readOnlyHint, openWorldHint, etc.), and the presence of an output schema, the description is complete. It covers purpose, usage, behavioral context, and return fields without needing to explain outputs or safety, as those are handled by structured data.

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

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

With 100% schema description coverage, the input schema fully documents the single parameter. The description adds no additional parameter semantics beyond implying the hash is for malware checking, so it meets the baseline of 3 without compensating for gaps.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('Look up a file hash') and resource ('MalwareBazaar database') with a distinct purpose ('to check if it is a known malware sample'). It differentiates from sibling tools by specifying this is for hash-based malware checks, unlike general IOC lookups like 'ioc_lookup'.

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

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

It provides explicit guidance on when to use this tool ('when you have a suspicious file hash from logs, alerts, or forensic analysis and need to determine if it is malicious') and when not to ('For general IOC lookups that auto-detect indicator type, use ioc_lookup instead'), clearly naming 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 cover key traits (read-only, open-world, idempotent, non-destructive), but the description adds valuable context: 'auto-detecting its type' explains the tool's intelligence, 'querying abuse.ch threat feeds' specifies the data sources, and 'no authentication required' clarifies access requirements. It doesn't contradict annotations and provides operational details beyond them.

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

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

The description is efficiently structured: it starts with the core purpose, explains usage guidelines, specifies alternatives, and details the return format. Every sentence adds value without redundancy, and it's front-loaded with the most critical information. The length is appropriate for the tool's complexity.

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

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

Given the tool's complexity (auto-detection, multiple threat feeds), rich annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage, alternatives, behavioral context, and data sources, leaving no significant gaps for an agent to understand 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?

The input schema has 100% description coverage, fully documenting the single 'indicator' parameter. The description doesn't add any parameter-specific details beyond what's in the schema, but it does reinforce the auto-detection capability for IOC types. With high schema coverage, the baseline score of 3 is appropriate as the description adds minimal parameter semantics.

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

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

The description clearly states the tool's purpose: 'Enrich an Indicator of Compromise (IOC) by auto-detecting its type and querying abuse.ch threat feeds.' It specifies the exact threat feeds used (ThreatFox, URLhaus, Feodo) and distinguishes it from siblings like 'hash_lookup' and 'threat_intel', making the purpose specific and well-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Use this as the primary tool for threat hunting when you have a suspicious indicator but don't know its type.' It also specifies alternatives: 'For malware-specific hash lookups with file metadata, use hash_lookup instead. For domain-only threat checks, use threat_intel instead.' This clearly defines usage context and exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations by stating 'no authentication required' and specifying the return format (JSON with detailed fields), which helps the agent understand the tool's behavior and output structure.

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

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

The description is efficiently structured: first sentence states purpose and scope, second provides usage contexts, third gives sibling differentiation, and fourth specifies output format and behavioral notes. Every sentence adds value with zero 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 tool's complexity (comprehensive intelligence retrieval), the description provides complete context: clear purpose, usage guidelines, sibling differentiation, output format details, and behavioral notes. With annotations covering safety/behavioral hints and an output schema presumably detailing the JSON structure, the description fills all necessary gaps.

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

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

Schema description coverage is 100%, with the schema fully documenting the single 'ip' parameter (type, format examples). The description doesn't add any parameter-specific semantics beyond what the schema provides, so 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 explicitly states the verb ('Retrieve comprehensive intelligence') and resource ('about an IP address'), listing specific intelligence types (geolocation, PTR record, etc.). It clearly distinguishes from sibling 'asn_lookup' by specifying network-level info is handled elsewhere.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('investigate suspicious IPs from logs, identify the owner of an IP, or assess whether an IP is malicious') and when-not-to-use alternatives ('For network-level info (ASN, IP ranges), use asn_lookup instead').

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

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

Beyond annotations (readOnly, idempotent), the description discloses rate limits (100/hr free, 1000/hr pro), error behavior (404 for non-KEV CVEs), and the return structure with specific fields like due_date, required_action, known_ransomware_use, etc. This adds significant behavioral 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 relatively long but well-structured. It front-loads the purpose and then provides details on usage, output, and rate limits. Every sentence adds value, though it could be slightly trimmed 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 single-parameter input and presence of annotations and output schema (described in text), the description is fully complete. It covers purpose, usage context, error handling, rate limits, and follow-up actions, leaving no gaps for the 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 a good description for cve_id. The description adds value by providing format examples (e.g., 'CVE-2021-44228') and clarifying the required format, which goes beyond the schema alone.

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

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

The description clearly states the verb 'Look up' and resource 'CISA KEV full record for a CVE'. It explicitly distinguishes from sibling cve_lookup (non-KEV CVEs) and suggests use after cve_search(kev=true), making the tool's purpose unmistakable.

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

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

The description provides explicit when-to-use (as follow-up after cve_lookup or cve_search with kev=true) and when-not-to-use (non-KEV CVEs should use cve_lookup). It also suggests chaining with cwe_lookup and mentions rate limits, giving clear 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?

While annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, the description adds valuable context about privacy protection ('only a 5-character prefix is sent'), data handling ('no data is stored, no files are accessed'), and the specific return format. It doesn't contradict annotations and provides additional behavioral insight.

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

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

The description is efficiently structured with three sentences that each serve distinct purposes: explaining the tool's function and method, clarifying behavioral aspects, and describing the return format. There's no redundant information, and key details are front-loaded.

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

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

Given the comprehensive annotations, complete schema coverage, and existence of an output schema, the description provides excellent contextual completeness. It covers the tool's purpose, privacy methodology, behavioral constraints, input requirements, and return format without needing to duplicate structured data.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaningful context about the parameter by specifying it must be 'a 40-char hex SHA-1 digest' and mentioning the k-anonymity method, which helps the agent understand the privacy implications of the input format.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('Check if a SHA-1 hash appears in the Have I Been Pwned breach dataset') and the method used ('using k-anonymity'). It distinguishes itself from sibling tools by focusing on password hash breach checking rather than general hash lookups or other security checks.

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

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

The description provides clear context about when to use this tool (for checking password hashes against HIBP with privacy protection), but doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools. The input requirement (40-char hex SHA-1) helps guide 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?

The description adds valuable behavioral context beyond annotations: it specifies the data source (URLhaus database), clarifies that no authentication is required, and describes the return format. While annotations cover read-only, open-world, and idempotent properties, the description provides practical implementation details that enhance 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 efficiently structured with zero waste: it states the purpose, provides usage guidelines with examples, distinguishes from siblings, describes the return format, and notes behavioral traits—all in a compact, front-loaded paragraph where every sentence serves a clear purpose.

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

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

Given the tool's moderate complexity, rich annotations, and the presence of an output schema (which handles return value documentation), the description is complete: it covers purpose, usage context, behavioral traits, and sibling differentiation without needing to duplicate structured data.

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

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

With 100% schema description coverage, the input schema already fully documents the single 'url' parameter. The description doesn't add additional parameter semantics beyond what's in the schema, so it meets the baseline expectation without extra value.

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

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

The description clearly states the tool's purpose with specific verb ('Check') and resource ('specific URL'), and explicitly distinguishes it from sibling tools like 'threat_intel' and 'ioc_lookup' by specifying it's for full URLs rather than domains or general IOC enrichment.

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

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

The description provides explicit guidance on when to use this tool ('when you have a full URL that you suspect may be malicious') and when to use alternatives ('For domain-level threat assessment, use threat_intel instead. For general IOC enrichment, use ioc_lookup'), offering clear context and exclusions.

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

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

The description adds valuable context beyond annotations: it specifies the return format ('Returns JSON with fields...'), mentions 'no authentication required', and implies a lookup service. Annotations already cover read-only, open-world, idempotent, and non-destructive aspects, so the description appropriately supplements without contradicting them.

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

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

The description is efficiently structured in three sentences: first states purpose and outputs, second provides usage scenarios and prerequisite, third specifies return format and behavioral notes. Every sentence adds value with zero waste, making it front-loaded and 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's moderate complexity, rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), 100% schema coverage, and presence of an output schema, the description is complete. It covers purpose, usage, behavioral context, and return format without needing to explain parameters or output details already documented elsewhere.

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

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

Schema description coverage is 100%, providing full documentation for the single parameter. The description adds minimal param semantics beyond the schema (e.g., 'The number must include the country code prefix' is implied in schema examples). Baseline 3 is appropriate as the schema carries the primary burden.

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

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

The description clearly states the specific action ('validate and analyze a phone number') and resource ('phone number'), listing detailed outputs (country, region, carrier, line_type, timezone, formatted versions). It distinguishes from siblings by focusing on phone number analysis rather than domains, IPs, emails, or other lookup types.

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

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

The description provides clear context for when to use the tool ('to verify phone number legitimacy, identify the carrier or country of origin, or detect VoIP numbers that may indicate fraud') and specifies a prerequisite ('The number must include the country code prefix'). However, it does not explicitly mention when not to use it or name specific alternatives among the sibling tools.

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

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

Description goes far beyond annotations by detailing SSRF-guarding (IP re-validation), hop limits, loop detection, truncation, per-target throttling with rate limits, and error response conditions (502, 429 with Retry-After). This provides a comprehensive behavioral picture that annotations alone (readOnlyHint, idempotentHint) do not cover.

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

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

The description is relatively long but every sentence serves a purpose: defining the tool, listing use cases, explaining behavior, constraints, and errors. It is front-loaded with the core function. Slightly verbose but justified given the tool's complexity; a minor trim 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 complexity (per-hop details, loop detection, throttling, error handling) and the presence of an output schema, the description covers all critical aspects: return fields, error responses, rate limits, and edge cases. No missing information needed for correct invocation.

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

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

The single parameter 'url' is fully described in the schema (coverage 100%). The description adds helpful context: 'Must start with http:// or https://' and 'Pass exactly as you'd curl -L'. This adds value beyond the schema's generic description, earning a score above baseline 3.

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

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

The description clearly specifies the verb (walk/analyze) and resource (HTTP redirect chain), and it lists exact use cases (deobfuscate URL shorteners, audit suspicious links, trace tracking redirects). It uniquely distinguishes itself from sibling tools like dns_lookup or ip_lookup by focusing on hop-by-hop redirect 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 explicitly states when to use the tool (for URL shorteners, phishing investigations, marketing redirects) and provides context on constraints (max 10 hops, loop detection, throttling). It does not explicitly state when not to use it, but the purpose is clear enough to infer alternatives; a minor improvement would be to mention scenarios where simpler tools suffice.

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

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

Despite comprehensive annotations (readOnly, openWorld, idempotent, not destructive), the description adds significant behavioral context: the custom User-Agent, opt-out mechanism, honoring Disallow for ContrastAPI, eTLD+1 throttling, and error response semantics. 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?

Dense single paragraph with front-loaded purpose. Every sentence adds distinct value (usage, edge cases, throttle, rate limits, return format, error handling). Could improve formatting with breaks, but highly efficient.

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

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

Given full schema coverage, annotations, and output schema referenced, the description provides complete context: usage, error handling, rate limits, throttling, and behavior details. 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 already covers domain format fully (100% coverage). Description does not add new parameter meaning beyond restating schema info, though it provides broader behavioral context about domain handling.

Input schemas describe structure but not intent. Descriptions should explain 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 starts with a clear verb+resource combination: 'Fetch + parse the target domain's robots.txt', and enumerates specific data items (sitemaps, allow/disallow rules, crawl-delay, Host directive). It distinguishes from other tools by explicitly mentioning it should be used before crawling/scraping tools like seo_audit, brand_assets, and redirect_chain.

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

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

Explicitly states when to use ('BEFORE crawling/scraping a target site') and lists specific tools. Provides clear guidance on handling 404 (implicit allow-all) and error cases (502 should not be interpreted as 'no robots'). Includes throttle and rate limit context, giving the agent actionable constraints.

Agents often have multiple tools that could apply. Explicit usage 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=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: it specifies the HTTP method (GET), clarifies no authentication is required, and describes the return format (JSON with specific fields). However, it doesn't mention rate limits, timeout behavior, or error handling.

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

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

The description is efficiently structured with three sentences: the first explains the core functionality, the second provides usage context and sibling differentiation, and the third covers behavioral details and output format. Every sentence adds essential information with zero 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 tool has comprehensive annotations, 100% schema coverage, and an output schema (implied by 'Returns JSON with fields'), the description provides complete contextual coverage. It explains what the tool does, when to use it, how it differs from alternatives, key behavioral traits, and the output structure - leaving no significant gaps.

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

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

Schema description coverage is 100% with a single well-documented 'domain' parameter. The description doesn't add any parameter-specific information beyond what's already in the schema (which includes examples like 'example.com'). This meets the baseline of 3 when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('perform a live HTTP request to a domain and analyze the security headers'), identifies the exact resources involved (six specific security headers), and explicitly distinguishes it from sibling tool 'check_headers' which validates existing headers rather than fetching them live. This provides precise verb+resource 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 explicitly states when to use this tool ('to audit a live website's header configuration') and when not to use it (vs. 'check_headers which validates headers you already have'). It provides clear context about the alternative tool by name and the specific scenario where this tool is appropriate.

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

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

Beyond annotations (readOnly, idempotent), description details ethical robots.txt handling, rate limits, cache behavior, error codes, and untrusted strings. No contradictions with annotations.

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

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

Description is comprehensive but slightly long. However, every sentence adds value, and key information (purpose, usage, rules, ethics) is front-loaded. Good structure with clear sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameter, output schema presence, and moderate complexity, the description covers audit rules, scoring, error conditions, ethics, rate limits, and cache behavior exhaustively. 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?

With 100% schema coverage for the single parameter 'domain', the schema already defines constraints. The description adds context (e.g., 'registrable domain') but doesn't substantially extend beyond schema. Score baseline 3, raised to 4 for added value.

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

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

The description clearly states the tool performs a one-shot SEO audit of a domain's homepage, outputting a composite score and missing_signals list. It distinguishes from siblings like audit_domain by emphasizing homepage-only scope and pre-pitch use.

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

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

Explicitly recommends use before pitching SEO work, triaging leads, or as pre-flight for deeper tools. Also states strict homepage-only and no crawling, providing clear when-not-to-use context.

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

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

The description adds valuable behavioral context beyond annotations by specifying 'Read-only TLS handshake, no authentication required' and detailing the connection method ('connecting to port 443'), which clarifies the tool's safe, non-destructive nature and operational approach, though it doesn't mention rate limits or error handling.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines and behavioral details, all in three efficient sentences with no redundant information, making it easy to parse and highly actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), and the presence of an output schema (implied by the detailed return fields listed), the description is complete enough, covering purpose, usage, behavior, and output structure without needing to explain return values in depth.

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

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

With 100% schema description coverage, the input schema fully documents the single 'domain' parameter. The description does not add any parameter-specific details beyond what the schema provides, such as format examples or edge cases, so 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 states the tool's purpose with specific verbs ('analyze', 'inspect') and resources ('SSL/TLS certificate and connection security of a domain'), distinguishing it from siblings like 'dns_lookup' or 'whois_lookup' by focusing on TLS handshake analysis rather than DNS or registration data.

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

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

The description provides clear context for when to use the tool ('verify certificate validity, detect expiring certificates, or audit TLS configuration strength'), but does not explicitly mention when not to use it or name specific alternatives among the sibling tools, such as 'check_headers' for HTTP header analysis.

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

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

Annotations cover read-only, non-destructive, idempotent, and open-world aspects, but the description adds valuable context: it specifies the passive nature ('non-intrusive'), clarifies that no authentication is required, and mentions the return format ('JSON with a subdomains array'), enhancing understanding beyond annotations 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 front-loaded with the core purpose, followed by usage guidelines, behavioral traits, and output details in three efficient sentences. Every sentence adds value without redundancy, making it highly concise and well-structured.

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

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

Given the tool's complexity (passive enumeration with multiple methods), rich annotations, 100% schema coverage, and presence of an output schema, the description is complete. It covers purpose, usage, behavioral context, and output format, leaving no significant gaps for the agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the single parameter 'domain'. The description does not add extra parameter details beyond what the schema provides, but it implies the domain is used for subdomain discovery, aligning with the schema's purpose. Baseline 3 is appropriate as the schema handles 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 specific action ('discover subdomains of a domain') and methods ('passive methods: Certificate Transparency log searches and DNS common-name brute-forcing'), distinguishing it from siblings like 'dns_lookup' or 'domain_report' by focusing on subdomain enumeration rather than general DNS or domain 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?

It explicitly states when to use this tool ('to map an organization's attack surface or find forgotten/exposed services') and when not to use it ('passive, non-intrusive enumeration — it does not actively probe discovered hosts'), providing clear context and exclusions compared to more active tools in the sibling list.

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

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

Annotations already cover key behavioral traits (read-only, open-world, idempotent, non-destructive). The description adds valuable context beyond annotations: it specifies the method ('Read-only HTTP request'), authentication requirements ('no authentication required'), and what data sources are analyzed (headers, meta tags, JS includes). No contradictions with annotations exist.

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

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

The description is efficiently structured: first sentence defines the tool's function, second lists detection capabilities, third provides usage guidance, and fourth covers behavioral and output details. Every sentence adds value with zero waste, making it easy to parse.

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

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

Given the tool's moderate complexity, rich annotations (covering safety and behavior), and the presence of an output schema (implied by the return format description), the description is complete. It explains the tool's purpose, usage, method, authentication, and output format, leaving no significant gaps for an agent to understand and invoke it correctly.

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

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

Schema description coverage is 100%, with the single parameter 'domain' well-documented in the schema. The description does not add further parameter details beyond implying the domain is used for technology detection. This meets the baseline of 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose with specific verbs ('identify', 'analyze', 'detects') and resources (HTTP headers, HTML meta tags, JavaScript includes), listing concrete examples of what it detects (WordPress, React, Cloudflare). It distinguishes itself from siblings by focusing on technology stack identification rather than DNS, security checks, or other reconnaissance functions.

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

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

Explicitly states when to use this tool: 'Use this for reconnaissance to understand what software a target runs.' This provides clear context for its application in security or analysis scenarios, differentiating it from siblings that might perform different types of reconnaissance (e.g., DNS lookups, threat reports).

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

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

The description adds valuable context beyond annotations: it specifies the threat feeds used ('URLhaus and abuse.ch'), notes that it's a 'read-only threat feed query' (which aligns with readOnlyHint=true), and states 'no authentication required' (useful operational detail not covered by annotations). It also describes the return format, which is helpful since annotations don't cover output behavior. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, followed by usage guidelines and output details. Every sentence adds value: the first defines the tool's function, the second provides usage context and alternatives, and the third covers output and behavioral traits. No wasted words, and it's structured for easy parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), 100% schema coverage, and the presence of an output schema, the description is complete. It covers purpose, usage guidelines, behavioral context (threat feeds, authentication), and output summary, leaving no significant gaps for the agent to operate effectively.

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

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

The description does not add meaning beyond the input schema, which has 100% coverage and already describes the 'domain' parameter adequately. The baseline score of 3 is appropriate since the schema fully documents the single parameter, and the description focuses on usage and output instead.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action ('Check if a domain is associated with malware distribution, botnet C2, or other malicious activity') and the resources involved ('URLhaus and abuse.ch threat feeds'). It distinguishes this tool from siblings like 'phishing_check' and 'ioc_lookup' by specifying domain-level checks versus URL or file-based IOC lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('to assess whether a domain is safe to visit or interact with') and when not to use it, providing clear alternatives: 'For checking a specific URL (not just domain), use phishing_check instead. For file-based IOC lookups, use ioc_lookup.' This gives precise guidance on tool selection 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?

The description adds valuable behavioral context beyond annotations: it specifies 'no authentication required' (though annotations don't cover auth), mentions it's a 'read-only orchestrated lookup' (reinforcing annotations), and describes the orchestration nature (combining multiple data sources). It doesn't contradict annotations (which correctly indicate read-only, non-destructive, idempotent, open-world).

Agents need to know what a tool does to the 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 front-loaded: first sentence states the core purpose, second provides usage context, third describes return format, fourth adds behavioral details. Every sentence earns its place with no wasted words. The description is appropriately sized for a complex 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 (orchestrating multiple data sources), the description provides excellent context: purpose, usage guidelines, behavioral details, and return format overview. With annotations covering safety profile and an output schema existing (mentioned in description), the description is complete enough for an agent to understand when and how to use this tool effectively.

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

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

Schema description coverage is 100%, so the schema already fully documents the single 'ip' parameter. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., doesn't elaborate on IP format constraints or validation rules). Baseline 3 is appropriate when 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's purpose: 'Comprehensive IP threat report in a single call' with specific details about what data sources it combines (Shodan InternetDB, AbuseIPDB, full Shodan, ASN ownership). It distinguishes from sibling tools like 'ip_lookup' or 'threat_intel' by emphasizing the comprehensive, multi-source nature in a single call.

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

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

Explicitly states when to use this tool: 'Use this for SOC triage and threat hunting when you need a complete IP profile without making 4+ separate requests.' It also provides exclusion guidance by contrasting with making multiple separate requests, and mentions the specific use cases (SOC triage, threat hunting).

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it specifies that the tool performs 'read-only HTTP checks to public profile pages, no authentication required,' which clarifies the operational method and access requirements, though it doesn't detail rate limits or error handling.

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

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

The description is front-loaded with the core purpose, followed by usage context, return format, and behavioral details in three concise sentences. Every sentence earns its place by adding distinct value (e.g., listing platforms, specifying OSINT use, detailing output and HTTP method), with no redundant or vague phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (single parameter, read-only operation), rich annotations (covering safety and idempotency), and the presence of an output schema (implied by 'Returns JSON with fields'), the description is complete. It adequately explains the purpose, usage, behavior, and output without needing to reiterate structured data, leaving no significant gaps 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 description coverage is 100%, with the input schema fully documenting the single required parameter 'username' (including format examples like 'torvalds'). The description adds minimal semantic value beyond the schema, only implying the parameter's use for cross-platform searches without providing additional syntax or constraints.

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

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

The description clearly states the specific action ('Search for a username across multiple social media and developer platforms') and resource ('username'), distinguishing it from sibling tools like email_lookup or phone_lookup by focusing on username-based OSINT investigations. It explicitly lists the platforms covered, making the scope unambiguous.

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

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

The description provides explicit guidance on when to use this tool ('for OSINT investigations to map a person's online presence or verify identity claims') and when not to use it (implied by the focus on usernames vs. other identifiers like emails or phone numbers in sibling tools). It also clarifies the context as read-only HTTP checks without authentication, setting clear boundaries.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive properties. The description adds valuable context about the data source ('Internet Archive API'), authentication requirements ('no authentication required'), and return format ('Returns JSON with fields...'), enhancing behavioral understanding 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 front-loaded with the core purpose, followed by usage guidance, alternative tool reference, return format, and behavioral notes. Every sentence adds value with zero wasted words, making it highly efficient.

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

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

Given the tool's moderate complexity, rich annotations, and existence of an output schema, the description provides complete context. It covers purpose, usage, alternatives, return format, data source, and authentication, leaving no significant gaps for the 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 description coverage is 100%, providing full parameter documentation. The description does not add any parameter-specific details beyond what's in the schema, so it meets the baseline for high schema coverage without extra value.

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

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

The description clearly states the specific action ('Retrieve historical web archive snapshots') and resource ('for a domain from the Wayback Machine'), distinguishing it from siblings like 'domain_report' by focusing on archive snapshots rather than broader security overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 on when to use this tool ('investigate domain history, verify how long a site has existed, or detect changes in content over time') and when to use an alternative ('For a broader security overview of a domain, use domain_report instead').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context beyond annotations by specifying 'no authentication required' and detailing the return format (JSON with specific fields), though it doesn't mention rate limits or error conditions.

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

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

The description is efficiently structured with three sentences: purpose, usage guidelines, and behavioral details. Every sentence adds value without redundancy, and key information is front-loaded.

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

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

Given the tool has comprehensive annotations, 100% schema coverage, and an output schema (implied by 'Returns JSON with fields'), the description provides complete contextual information. It covers purpose, usage differentiation, and additional behavioral context needed for effective tool selection.

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

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

Schema description coverage is 100% with a single parameter clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 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 states the specific action ('Retrieve WHOIS registration data') and resource ('for a domain'), listing key data fields. It distinguishes from sibling 'domain_report' by specifying this tool focuses solely on WHOIS data, not a full security overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('to determine domain ownership, age, or expiration status') and when to use an alternative ('For a full security overview that includes WHOIS, use domain_report instead'). This provides clear decision-making guidance.

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