ContrastAPI

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

Despite annotations already flagging readOnlyHint, idempotentHint, and destructiveHint, the description adds important behavioral details: default prefix truncation to 50 per family, the availability of include_full_prefixes to get the full list, and rate limits ('Free: 30/hr, Pro: 500/hr'). It also clarifies that ipv4_count/ipv6_count are honest pre-truncation totals. No contradictions with annotations.

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

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

The description is well-structured and efficient. It opens with the purpose, then use case, then behavioral details (truncation, rate limits), and closes with the return shape. Every sentence adds value; no filler or redundancy.

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

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

The tool is simple (2 params, 1 required) and has an output schema per context signals. The description covers purpose, use case, parameter behavior, rate limits, and return fields, providing everything an agent needs to select and invoke the tool correctly. 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 description coverage is 100%, so the baseline is 3. The description reinforces parameter behavior (e.g., 'set include_full_prefixes=True for full list') but does not add meaning beyond what the schema already provides for each parameter. The return-object mention offers slight context, but parameters are fully documented in the schema.

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

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

The description clearly states the tool's function: 'Look up Autonomous System Number (ASN) for a domain or IP' and specifies the returned data (AS number, organization, IPv4/IPv6 prefixes). It distinguishes itself from sibling tools like ip_lookup or whois_lookup by focusing on ASN and network ownership, using a specific verb+resource structure.

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

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

The description provides a clear use case: 'Use to identify network operator and IP range ownership.' This gives context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools. That fits the 'clear context, no exclusions' level.

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

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

Discloses several behavioral traits beyond annotations: slim vs. full response (truncation to 240 chars), the include parameter impact, rate limits (30/hr free, 500/hr Pro), 404 behavior, and the output shape including next_calls. This adds substantial context about response size, error handling, and throttling, going well beyond the readOnly/idempotent annotations.

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

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

The description is information-dense but every sentence contributes: resource definition, parameter behavior, usage workflow, error behavior, rate limits, and output fields. It is well-structured, front-loaded with the tool's purpose, and avoids filler or repetition.

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

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

Given the tool's moderate complexity (2 params, output schema present), the description is complete: it covers return key fields, error responses, rate limits, and how to use companion tools. The output schema handles detailed return structure, so the description need not enumerate all fields, making this appropriately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: explains that the default include is slim, that 'full' gives verbose narrative, and provides example ID format (AML.CS####). This helps the agent understand the intent of each parameter and the impact of the include choice, adding value over the raw schema.

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

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

The description clearly identifies the tool as a lookup for MITRE ATLAS case studies (documented AI/ML attack incidents) and states what each case study contains (techniques_used). It distinguishes from siblings by specifying the resource (case study vs. technique or search) and points to related tools for search and bulk 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 describes the intended workflow: use after atlas_technique_search to find incidents using a technique, and use bulk_atlas_technique_lookup to drill into techniques_used. Also notes the next_calls hint and the 404 error for invalid IDs, providing clear context for when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: default SLIM response with 240-char truncation, the include='full' parameter to override, rate limits ('Free: 30/hr, Pro: 500/hr'), and the exact return shape including next_calls. This goes well beyond what annotations convey and does not contradict 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?

Three sentences with no waste. The first sentence states the core purpose, the second adds the key behavioral detail (slim vs. full) and use case, and the third covers pricing, return structure, and sibling differentiation. Every sentence earns its place.

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

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

Given full schema coverage, clear read-only/idempotent annotations, an output schema, and a description that covers default behavior, rate limits, return fields, and an alternative tool, the description fully equips an agent to select and invoke this tool without unresolved ambiguity.

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

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

The input schema has 100% coverage with all four parameters documented in detail (e.g., 'Substring match... Min 2 chars', 'format AML.T####'). The description echoes these concepts at a high level ('by keyword or referenced technique') but adds no parameter-specific meaning that isn't already in the schema.

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

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

The description clearly states the tool's function: 'Search ATLAS case studies (real-world AI/ML attack incidents) by keyword or referenced technique.' It distinguishes itself from the sibling atlas_case_study_lookup by explicitly saying 'Drill via atlas_case_study_lookup for the full procedure list,' and gives a specific use case: 'Useful when the user has a technique in hand and wants to see incidents that exercised it.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the tool ('Useful when the user has a technique in hand...') and names an alternative for deeper investigation ('Drill via atlas_case_study_lookup for the full procedure list'). This gives the agent clear decision criteria for choosing between these two siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful behavioral context: rate limits (30/hr free, 500/hr Pro), 404 behavior when the id is not found, sub-technique inherited_tactics flag, maturity levels, and ATT&CK bridging behavior. No contradiction with annotations. This goes well beyond the basic safety hints.

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

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

The description is longer than strictly necessary, but it is front-loaded with the primary purpose and each sentence contributes distinct value (ATLAS explanation, ATT&CK bridge, inheritance, usage guidance, errors, rate limits, output fields). Minor redundancy exists (e.g., listing example attack types is not essential), but the structure is logical and readable. Slightly verbose, so 4.

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

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

For a single-parameter tool with a rich output schema, the description is exceptionally complete. It covers what the tool does, when to use it, alternatives, error behavior, rate limits, inherited sub-technique behavior, and the full return field list. There are no significant gaps in context needed for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% with technique_id format and examples fully documented in the input schema. The description does not add parameter-specific meaning beyond the schema, though it does reinforce the context (e.g., 'AML.T0051' LLM Prompt Injection). Baseline 3 is appropriate since the schema already handles 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 opens with a specific verb+resource: 'Look up a MITRE ATLAS technique.' It distinguishes from siblings by explicitly naming bulk_atlas_technique_lookup for multiple techniques and describing ATLAS as the AI/ML adversarial attack catalog with examples like prompt injection and model evasion. This makes the tool's purpose unmistakable and distinct from related lookup/search tools.

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

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

The description gives explicit when-to-use guidance: 'Use this tool when the user asks about AI/ML threats, LLM red-teaming, or adversarial ML.' It also names an alternative for multiple techniques: 'for multiple techniques in one call... prefer bulk_atlas_technique_lookup.' Additionally, it suggests pivoting to d3fend_defense_for_attack and CVE search via attack_reference_id, providing clear context for related follow-ups.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral traits: default SLIM responses with 240-char truncation, include='full' toggle with size warning (~100KB), rate limits (30/hr free, 500/hr Pro), and the return structure including next_calls. There is no contradiction with annotations.

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

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

The description is dense but logically ordered: purpose, default behavior, usage guidance, rate limits, and return format. Every clause adds operational value without restating schema fields verbatim. Length is appropriate given the richness of context provided.

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

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

For a 6-parameter tool with all optional inputs, the description covers discovery use cases, drill-down paths, cross-reference bridges, rate limits, and the full output schema. It leaves no ambiguity about what the agent will receive or how to chain subsequent calls.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of exclude_id ('skip self in sibling-tactic searches'), the exact truncation length, and the performance impact of include='full' on a 167-technique catalog. These nuances are not present in the schema, earning a 4.

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

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

The description opens with a specific verb ('Search') and names the resource ('MITRE ATLAS catalog of AI/ML attack techniques') with clear search facets (keyword, tactic, maturity). It effectively distinguishes from the sibling lookup tool by positioning this as the discovery entry point and explicitly directing users to atlas_technique_lookup 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?

It explicitly states when to use this tool ('Use this to discover techniques matching a threat-model question') and provides concrete chaining guidance (exclude_id, drill into atlas_technique_lookup). It also names the downstream cross-reference path via d3fend_defense_for_attack, covering both tool selection and follow-up steps.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: default TXT filtering to security-relevant entries, the honest pre-filter count, token costs, and the emitted next_calls. This goes beyond the annotations without contradicting them.

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

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

The description is dense but well-organized, with a clear front-loaded purpose statement followed by parameter details, usage alternatives, and return structure. While it contains multiple sentences, each provides needed information; minor redundancy ('honest pre-filter count') could be trimmed, but overall it earns its length.

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

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

The description is comprehensive for a tool of this complexity. It covers rate limits (30/hr Free, 500/hr Pro), token cost, response fields, default filtering behavior, and chaining recommendations. Since an output schema exists, the listed return keys are sufficient, and the description addresses operational aspects not in structured fields.

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

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

Schema coverage is 100%, so both parameters are well-described. The description adds extra meaning by explaining the include_all_txt default filter behavior, the total_txt_records field, and how the domain parameter relates to the overall audit. This enrichment justifies a score above the baseline of 3.

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

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

The description clearly states the tool's function: 'Perform comprehensive domain audit: combines domain_report + live HTTP security headers + technology fingerprinting.' It distinguishes itself from siblings by explicitly naming domain_report as a passive-only alternative and by mentioning next_calls to subdomain_enum and ssl_check.

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

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

The description provides explicit usage guidance: 'Use when you need the full picture (recon + active checks); use domain_report for passive-only assessment.' It also explains when to pass include_all_txt=true and how to chain next_calls, offering clear context for when to use this tool versus alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral details: robots.txt handling with exact error code, Cache-Control respect with cache_respected flag, per-target throttle of 60 req/min, untrusted URL fields warning, API quotas, and error return codes (502, 403). This is substantial added value.

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

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

Although long, every sentence earns its place: purpose, use cases, restrictions, ethics, rate limits, security, quotas, and return shape are all covered. The core purpose is front-loaded in the first sentence, making it efficient 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?

With one parameter, rich annotations, and an output schema, the description still adds essential operational context: error scenarios, cache behavior, rate limiting, security warnings, and allowed use cases. It fully equips the agent to invoke the tool correctly and interpret responses.

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

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

Schema coverage is 100% for the domain parameter, but the description adds meaningful details: 'No scheme, no path, no port' and 'fetches https://<domain>/ with HTTP fallback'. This goes beyond the schema's basic definition.

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

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

The description starts with a specific verb 'Scrape' and resource 'a domain's homepage <head>', listing exact assets (favicon, og:image, etc.). It clearly distinguishes from siblings like seo_audit or tech_fingerprint by focusing on brand assets and explicitly stating homepage-only scope.

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

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

The description provides concrete use cases ('enrich CRM records, build company-card UIs, or correlate a lead's site to their visual identity') and clear constraints ('Strictly homepage-only (path /); we do NOT crawl'). It lacks explicit alternative tool names but gives enough context for the agent to choose appropriately.

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

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

Despite annotations already declaring readOnly/idempotent/destructive flags, the description enriches behavior with per-item details: 'parent-tactics inheritance... inherited_tactics=true flag,' 'per-item next_calls' with D3FEND/sibling/parent options, and the response envelope including partial-failure statuses. This goes well beyond structured metadata.

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

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

Though long, the description front-loads the core purpose in the first clause and then packs each subsequent sentence with necessary detail (per-item shape, next_calls, rate limits, return structure). No filler; the length is justified by 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?

The description covers the full usage lifecycle: when to use, input constraints, per-item result shape with error statuses, follow-up actions from next_calls, rate limits, and the top-level response fields. With output schema and annotations present, nothing critical is missing.

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

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

Schema covers technique_ids with format, max, case-insensitivity, normalization/de-dup, and per-item rate count (100% coverage). The description does not add new param semantics beyond restating the 50-technique limit, so baseline 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?

Clearly states 'retrieve full records for up to 50 techniques in a single request' and contrasts with 'N separate atlas_technique_lookup calls,' distinguishing it from the sibling single-lookup tool. Also names the natural predecessor (atlas_case_study_lookup), making the purpose concrete.

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

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

Explicitly frames it as 'instead of N separate atlas_technique_lookup calls' and as 'the natural follow-up to atlas_case_study_lookup,' telling the agent when to choose this bulk tool. Also notes rate-limit implications (1 per item), helping with batch planning.

Agents often have multiple tools that could apply. Explicit usage 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 safe read-only/idempotent behavior. The description adds crucial behavioral details: truncation defaults (20 affected_products, 10 references), flag effects, the addition of next_calls for chaining, rate limits, and the top-level return object. It also notes honest counts (total_products/total_references). This exceeds the annotation baseline and facilitates correct invocation.

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

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

The description is a single dense paragraph but well-structured: purpose → defaults → flags → use cases → chaining → limits → return shape. Every sentence provides non-redundant information. It is appropriately sized for a tool with 5 parameters and complex behavior.

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

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

Given the output schema exists and annotations cover safety, the description covers all necessary contextual aspects: batch size limit, when to use vs cve_lookup, output structure, rate limits, and chaining. It even highlights the 'honest count' behavior. No critical gaps are present.

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

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

With 100% schema coverage, the baseline is 3, but the description goes beyond the schema by explaining the practical impact of each boolean (e.g., 'pass include_affected_products=true to return full lists,' 'include_severity_breakdown... cvss_v2 and cvss_v2_vector are always emitted'). It clarifies defaults and trade-offs (e.g., 'Set False for legacy clients'). This adds meaning beyond the schema.

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

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

The description immediately states 'Batch query multiple CVEs' and specifies 'retrieve full CVE details for all in 1 request instead of N.' It explicitly distinguishes from sibling cve_lookup by saying 'use cve_lookup for single CVE.' This provides a clear verb+resource+scope and differentiates it from the single-CVE tool.

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

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

It gives explicit use cases: 'Use for dependency audits or bulk vulnerability enrichment; use cve_lookup for single CVE.' It also provides chaining guidance with kev_detail, cwe_lookup, and exploit_lookup based on conditions in the response. Rate limits are stated for Free and Pro tiers, making the guidance highly actionable.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description details auto-detection of indicator types, queries against abuse.ch feeds per indicator, per-type source coverage, per-indicator verdict with sources_queried/sources_unavailable for partial failures, and rate limits. This is substantial behavioral context not present in annotations.

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

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

The description is dense and information-rich, with each sentence serving a purpose (behavior, use case, rate limits, output). However, it is a single multi-clause block of about 5-6 sentences; while efficient, breaking it into bullets or shorter sentences would improve readability. Still, no fluff and well 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 (batch, multiple IOC types, partial failures, rate limits), the description covers source coverage per type, failure visibility, rate limits, and the summary return fields. Since an output schema exists, it needn't explain return values in depth. This is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining per-item rate limit counting ('1 per item') and that rate limits are 'same for Free and Pro', which is not in schema. It also clarifies that auto-detection plus per-indicator feed queries happen, but some of this is already in the schema description.

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

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

The description clearly states the tool 'Batch query multiple IOCs... in 1 request' with specific supported types (IP/domain/URL/hash) and a limit of 50 per call. It explicitly contrasts with 'use ioc_lookup for single indicator', differentiating it from its sibling.

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

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

Provides explicit guidance: 'Use for SOC alert triage or batch enrichment; use ioc_lookup for single indicator.' This directly tells the agent when to use this tool versus the alternative, and also mentions per-type source coverage matching ioc_lookup, setting expectations.

Agents often have multiple tools that could apply. Explicit usage 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 per-item status handling (ok/not_found/invalid_format), quota consumption per rule_id, graceful degradation via skipped_due_to_rate_limit, Free/Pro limits, and the exact return structure—substantially exceeding the baseline.

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

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

The description is compact yet rich, front-loaded with purpose, and every sentence conveys essential information without redundancy.

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

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

With a complete schema, output schema, and annotations, plus detailed rate-limit and error-handling context, the description leaves no significant gaps for an agent to misuse the tool.

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

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

The schema already fully documents rule_ids (format, max 50, per-item validation, quota). The description adds no new parameter-level semantics; it mostly repeats or discusses output behavior, so baseline 3 applies.

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

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

The description explicitly states it retrieves full records for up to 50 rule UUIDs in a single request, and contrasts with sigma_rule_lookup, making its purpose unambiguous and distinguishing it from siblings.

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

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

It provides explicit guidance: designed for triage workflows where multiple rule ids are known, and positioned as an alternative to N separate sigma_rule_lookup calls. It also notes parity with bulk_cve/ioc for rate-limit behavior, helping the agent decide when to use it.

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

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

Annotations already mark readOnly, idempotent, and non-destructive; the description adds the scoring formula, multiplicative boosters, clamping to [0,100], label bands, urgency/SLA mapping, rate limits, and the limitation that PoC comes only from the local ExploitDB mirror. This goes far beyond what annotations provide and gives the agent a clear understanding of behavior.

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

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

The description is long but every sentence serves a purpose: formula, boosters, labels, urgency, usage guidance, limitation, attribution, rate limits, and return object fields. It is structured from high-level purpose down to details, with no filler and a clear hierarchy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 composite risk-scoring tool with one input, the description covers the algorithm, edge-case boosters, output bands, urgency policy, rate limits, and scope limitations. An output schema exists, and the description still previews key return fields. This is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has a single parameter cve_id with 100% description coverage, including format and example. The description does not add new semantic meaning for the parameter beyond clarifying the tool consumes a single CVE ID, which is already evident from the schema. Baseline 3 applies because the schema fully documents the parameter.

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

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

Description states 'Composite CVE risk score (0-100) — fuses CVSS, EPSS, KEV, and PoC into a single agent-ready triage signal.' It clearly identifies the tool's function and differentiates from siblings by noting it avoids orchestrating cve_lookup + exploit_lookup separately, and explicitly contrasts with exploit_lookup for PoC detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 triage a single CVE without orchestrating cve_lookup + exploit_lookup separately' and 'for full multi-source exploit detail... call exploit_lookup separately.' This states when to use the tool, what it is not for, and names the alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the base safety profile is known. The description adds meaningful behavioral context: rate limits (30/hr Free, 500/hr Pro), the exact return structure ({findings, total, by_severity, summary}), and an important edge case where 'fixed_in' is omitted for open-ended version ranges, affecting remediation copy. This goes beyond what annotations provide, though not to the level of a full protocol explanation.

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

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

The description is information-dense but well-organized: first sentence gives the core purpose, then rate limits, return shape, and a detailed edge case. Every sentence carries substantive information; no filler. It is longer than minimal but justified by the tool's complexity and the value of the edge-case explanation.

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

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

For a tool with one parameter and a rich output schema, the description covers the essential context: purpose, usage boundaries, rate limits, response format, and a nuanced behavior (fixed_in omission). Since an output schema exists, return values are already documented, but the description still explains the shape and key edge cases, making it exceptionally complete for an agent to select 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?

The schema already provides 100% coverage of the 'packages' parameter with field descriptions, examples, and constraints. The description reinforces this by explicitly stating the maximum of 50 items, noting that only 'name' and 'version' are used and extra fields ignored, and reiterating the example. This adds operational detail beyond the schema, though the schema itself is already strong.

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

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

The description starts with 'Audit project dependencies... against CVE database: find known vulnerabilities in your package list,' which is a specific verb+resource+scope. It explicitly distinguishes itself from cve_lookup ('use cve_lookup for single CVE'), making it clear this is for bulk dependency scanning.

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

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

Provides explicit when-to-use guidance: 'Use for dependency security scanning; use cve_lookup for single CVE.' Also specifies bulk query limits (up to 50 packages per call, same for Free and Pro) and rate limits, giving clear operational context for choosing this tool over alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it discloses that no external requests are made, describes the default truncation of header values to 500 chars, explains the include='full' option, and specifies the return shape ({total, by_severity, findings}). Annotations already indicate read-only and idempotent, but the description enriches the behavioral profile substantially.

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

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

The description is compact and well-structured: purpose, use cases, rate limit, truncation behavior, return format, and privacy note are all conveyed in just a few sentences. Every sentence contributes unique information without redundancy or fluff.

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

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

For a two-parameter tool with an output schema, the description is highly complete. It covers when to use, alternatives, behavioral details (truncation, no external requests), rate limits, and return format. The existence of an output schema means it need not explain return values in depth. The description leaves no major gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by enumerating the specific security headers to validate (CSP, HSTS, etc.), which helps the agent construct meaningful input. It also reinforces the include parameter's truncation behavior, though this is already in the schema. Overall, a modest addition over schema.

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

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

The description clearly states the tool validates user-provided HTTP security headers against best practices, listing specific header types (CSP, HSTS, X-Frame-Options, etc.). It also distinguishes from the sibling tool by directing users to scan_headers for live fetching, so there is no ambiguity about what this tool does.

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

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

Explicit usage guidance is provided: 'Use to test header config before deployment or validate non-public servers; use scan_headers to fetch live.' This tells the agent exactly when to choose this tool over the alternative, and also includes rate limit information ('Free: 30/hr, Pro: 500/hr') that affects 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 declare readOnly, idempotent, non-destructive, and the description adds valuable behavioral context beyond that: rate limits ('Free: 30/hr, Pro: 500/hr'), privacy ('No data stored'), and the return shape ('Returns {total, by_severity, findings}'). It also notes supported languages, which are capabilities not 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 front-loaded with the primary action, then systematically provides vulnerability types, supported languages, usage guidance, companion tools, rate limits, return format, and privacy guarantee. Every sentence carries distinct information without redundancy, achieving high information density in a compact form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 2 parameters and an output schema, the description covers all essential context: inputs (source code, language), capability, alternatives, rate limits, return structure, and data handling. The output schema defines the findings structure, so the description does not need to expand return values further. No significant gaps remain.

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

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

Schema description coverage is 100%: both `code` and `language` are fully described in the input schema, including the enum values and default. The description does not add new semantic details for the parameters themselves; it only reiterates language support at a high level, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Scan source code for injection vulnerabilities' which is a specific verb+resource+objective. It lists concrete vulnerability types (SQL injection, command injection, path traversal) and explicitly differentiates from sibling tools by directing secrets scanning to check_secrets, establishing a unique purpose within the companion set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage context ('Use to detect input-handling bugs') and explicitly names alternatives: 'for secrets use check_secrets', plus check_dependencies, check_headers, and scan_headers with their distinct purposes. This is clear when-to-use and when-not-to-use guidance, satisfying the criteria for explicit 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, and destructiveHint=false. The description adds valuable behavioral context: 'No data stored' (privacy), rate limits (Free/Pro), the return shape ({total, by_severity, findings}), and a nuanced suppression rule for the generic password-assignment rule. 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 a compact paragraph that front-loads the core purpose, then adds languages, usage, limits, output, and one behavioral nuance. Every sentence adds genuine value, though a few details (rate limits, suppression rule) could be seen as extra. Overall, well-structured and not verbose.

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

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

Given the tool's moderate complexity (multiple languages, output format) and the existence of an output schema, the description covers all key aspects: purpose, supported languages, explicit use case, rate limits, privacy, return shape, and a subtle edge-case rule. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters, so the schema already explains 'code' and 'language' fully. The description restates the supported languages but does not add new semantic details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Scan source code (or snippet) for hardcoded secrets,' and enumerates the types of secrets (cloud provider keys, API tokens, etc.). It also distinguishes itself from sibling tool check_injection by naming it as the alternative for injection detection, making the purpose clear and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('Use to detect leaked credentials before commit') and explicitly names an alternative ('for injection detection use check_injection'). It also provides supported languages, which helps the agent choose the tool appropriately.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond this: it explicitly states 'Active outbound fetch' and discloses the per-target eTLD+1 throttle and token costs. This transparently communicates that the tool makes real network requests and has rate/cost implications, which is essential behavioral information.

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

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

The description is dense and information-packed, covering purpose, modules, use cases, rate limits, pricing, and return structure in a few sentences. It is well-front-loaded with the core purpose, though the enumeration of 11 modules and return fields makes it somewhat long. Every sentence contributes value, earning a score above average but not perfect due to density.

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

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

Given the tool's complexity (11 modules, enrichment, multiple return fields), the description is remarkably complete. It explains the scan nature, the enrichment output, usage context, rate limits, quotas, and lists the full return object. An output schema exists, so detailed return field explanation is unnecessary, and the description fills the gaps 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 input schema covers 100% of the parameter semantics: 'domain' is fully described with format and rejection rules. The description repeats the concept of scanning a live site but adds no new parameter-level details beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool performs an active website security scan using the ContrastScan C engine with 11 named modules, and produces severity-ranked findings and a letter grade. It explicitly distinguishes itself from sibling tools by naming audit_domain and scan_headers 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?

Provides explicit guidance on when to use this tool ('hands-on misconfiguration scan') versus alternatives ('audit_domain for passive recon', 'scan_headers for headers only'). Also includes operational constraints such as rate limits (60 req/min) and quota details (Free/Pro), giving clear context for invocation.

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

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

Beyond the annotations (readOnlyHint=true), the description adds substantial behavioral context: the verdict is at the response root applying to the batch, the global hint pointing to cve_lookup, rate limits (30/hr free, 500/hr Pro), and the slim vs. full payload behavior. This goes well beyond what annotations provide.

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

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

The description is dense and information-rich, front-loaded with the core purpose. Every sentence earns its place (usage, payload behavior, response structure, rate limits), though it is slightly long. It could be tightened but remains efficient for the complexity it covers.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (pagination, include modes, response shape, verdict placement, hint), the description covers all essential aspects: purpose, alternatives, payload details, rate limits, and return object. The output schema also exists, so the description appropriately complements rather than duplicates return value documentation.

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

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

Schema coverage is 100%, but the description adds value by explaining the trade-off of the include parameter ('slim default avoids description/summary duplication that bloats 50-item leading lists') and clarifying that 'full' gives the 'same payload shape as cve_lookup'. This contextualizes parameter choices beyond the schema's raw definitions.

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

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

The description uses a specific verb ('List') and identifies the exact resource ('CVEs indexed from MITRE/GHSA BEFORE NVD publication'), which clearly distinguishes it from sibling tools like cve_search (published NVD data) and cve_lookup (drill-down). This is a model of purpose clarity.

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

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

Explicit guidance is given: 'Use for threat intelligence on emerging CVEs; use cve_search for published NVD data' and 'for drill-down on a single CVE prefer cve_lookup'. This directly addresses when to use this tool versus alternatives, exceeding basic usage context.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds rich behavioral context: default truncation of affected_products/references with 'honest count', behavior of include_* flags, tag-first patch detection, severity consensus logic, and rate limits. It also notes the 'disputed' tag effect on summary prefix.

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

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

The description is long but information-dense, using semicolons and lists to pack many details. Every sentence adds value—no redundancy or fluff. It is front-loaded with the core purpose and then expands into optional behaviors, making it easy to scan.

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

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

For a tool with 5 parameters, an output schema, and complex behaviors, the description covers the key use cases, return shape highlights, defaults, rate limits, and chaining opportunities. It fully supports an agent in deciding when and how to invoke the tool, even without seeing the output schema.

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

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

Schema coverage is 100%, but the description adds valuable context beyond the schema: e.g., 'By default affected_products is truncated to the first 20 entries', 'total_reports the honest count', and 'tag-first patch detection'. It clarifies the purpose and side effects of the boolean parameters without repeating their full schema descriptions.

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

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

The description opens with 'Retrieve detailed CVE data by ID', giving a specific verb, resource, and lookup key. It also explicitly distinguishes itself from cve_search: 'Use for single-CVE details; use cve_search for queries by product/severity.'

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

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

It clearly states when to use this tool ('single-CVE details') and when to use an alternative ('use cve_search for queries by product/severity'). It also explains when to pass optional flags (e.g., include_affected_products for bulk audits) and how to chain next_calls with kev_detail, cwe_lookup, and exploit_lookup.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behaviors: the default SLIM response with include='full' for detail, exact NVD-canonical token matching with examples, the global verdict at the response root, the response hint pointing to cve_lookup, rate limits (30/hr free, 500/hr Pro), and the meaning of low/zero counts. 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 information-dense and front-loaded with the primary purpose and filters. It is long but every sentence contributes a distinct piece of guidance (response format, token matching, alternatives, rate limits). It could be improved with bullet points or more distinct paragraph breaks, but no sentence seems wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (14 parameters, multiple caveats, and several sibling alternatives), the description covers the main use cases, non-obvious token behavior, output shape (with return object listed), and rate limits. The presence of an output schema further reduces the need to explain return values, making this description highly complete.

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

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

Schema description coverage is 100%, and the schema already documents all parameters thoroughly, including the exact-token caution, sentinel defaults for cvss_min/max, and include trade-offs. The description repeats this context and adds a condensed warning, but it does not meaningfully extend the parameter semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Search CVE database with filters', then enumerates the filter dimensions. It clearly distinguishes from sibling tools like cve_lookup (single CVE by ID) and kev_detail (KEV federal patch deadlines), so the purpose is unambiguous and 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 gives explicit guidance: 'Use for vulnerability discovery by criteria', 'Use cve_lookup for single CVE by ID', 'kev_detail when kev=true filtering', and 'for dependency/package lists use check_dependencies and for a domain's whole stack tech_stack_cve_audit'. It also mentions pairing with cwe_lookup and cve_lookup for drill-down, making when-to-use and alternatives explicit.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds significant behavioral details beyond that: default 'slim' vs 'full' response, truncation of mitigations/examples, the 'cve_count' lower-bound nuance, rate limits (30/hr, 500/hr), and 404 behavior. This gives the agent confidence in side effects and data semantics.

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

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

The description is long but densely packed. It front-loads the purpose, then logically flows into default behavior, parameter effect, return fields, usage guidance, error handling, and rate limits. Every clause earns its place, though the final 'Returns { ... }' list partially duplicates output schema information. It is efficient for the complexity, but slightly verbose.

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

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

For a tool with two parameters, one optional, and a rich output schema, the description is exceptionally complete. It covers default return shape, full detail mode, data semantics (lower-bound cve_count), error conditions, rate limits, and workflow integration with cve_lookup and cve_search. There are no significant gaps in what an agent needs to know to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics: it clarifies the effect of the 'include' parameter (slim vs full) and notes that 'total_mitigations / total_examples are always honest pre-truncation counts.' For 'cwe_id', the schema already provides format and common values, and the description does not repeat that unnecessarily. The added nuance about total counts and extended_description null behavior goes beyond schema descriptions.

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

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

The description clearly states the tool's function: 'Look up MITRE CWE catalog record from research view 1000.' It uses a specific verb ('look up') and resource ('CWE catalog record'), and adds scope ('research view 1000'). This distinguishes it from sibling tools like cve_lookup and atlas_technique_lookup, which focus on different databases. The purpose is unambiguous and not a tautology.

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

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

The description provides explicit guidance: 'Use after cve_lookup or kev_detail to understand the underlying weakness category; chain with cve_search(cve_id=...) to enumerate all matching CVEs.' This tells the agent exactly when and how to use the tool relative to others. It also notes the 404 error condition, adding practical usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rate limits (Free: 30/hr, Pro: 500/hr), return fields, and the concept of undefended_techniques as gaps worth flagging. This is substantial behavioral context beyond what annotations provide.

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

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

The description is multi-sentence but every sentence carries distinct value: purpose, usage scenario, definitions of output fields, a pairing suggestion, rate limits, and the return structure. It is front-loaded with the core purpose and contains no filler.

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

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

Covers input, output fields, usage context, rate limits, and next_calls. Since an output schema exists, the description doesn't need to explain return values in detail, but it still lists the key fields. It fully contextualizes the tool within its batch-assessment use case.

Complex tools with many parameters or behaviors need more documentation. 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 covers 100% of the param including maxItems, type, and an example. The main description only repeats 'list of ATT&CK T-codes' without adding new semantic detail, so it remains at the baseline 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 opens with 'Batch coverage breakdown: given a list of ATT&CK T-codes, return distinct defense counts per D3FEND tactic + identify which techniques have NO D3FEND mapping' — a specific verb+resource+scope. It clearly distinguishes from sibling d3fend_defense_for_attack by emphasizing batch assessment of an entire campaign.

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

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

States 'Use to assess the defensive posture of an entire attack campaign or threat model in one call' and explicitly recommends pairing with cve_search per gap, providing clear context and a complementary alternative. It doesn't explicitly exclude single-technique lookups, but the batch framing makes the usage context clear.

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

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

The description adds substantial behavior beyond the readOnlyHint/idempotentHint annotations, including truncation behavior ('defenses is capped at limit', 'total is the honest pre-truncation count'), response slim/full modes, the 'gap is itself a signal' empty-list case, and rate limits. This goes far beyond what annotations convey.

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

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

Though lengthy, every sentence provides unique value: purpose, use case, parameter semantics, output details, and rate limits are clearly separated and front-loaded. No filler or redundancy.

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

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

The description covers all necessary context: when to use, parameter nuance, output schema semantics (including truncated flag and coverage_by_tactic aggregation), error behavior (200 with empty list), and rate limits. With an output schema present, the return format explanation is complementary, and it fully prepares the agent for invocation.

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

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

Schema coverage is 100%, but the description enriches meaning for each parameter: limit's token-efficiency motivation, include's slim/full tradeoff, exclude_id's chaining purpose, and attack_technique_id's regex format. This transforms raw schema attributes into actionable guidance.

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

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

The description opens with a specific verb and resource: 'Reverse lookup: given an ATT&CK T-code, return D3FEND defenses that mitigate it.' It clearly differentiates from siblings like d3fend_defense_lookup and d3fend_attack_coverage by framing it as the offensive-to-defensive bridge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Pair with cve_lookup or atlas_technique_lookup output — when those carry an ATT&CK id, call this tool to surface the mitigations.' Also gives a chaining example with d3fend_defense_lookup via exclude_id, making the intended context clear.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds behavioral context by specifying the response structure, 404 behavior, and rate limits, which go beyond the annotation flags.

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

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

The description is dense but each sentence earns its place: main action, domain context (tactics), usage guidance, error case, rate limits, and return fields. It is longer than minimal but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 schema, strong annotations, and presence of an output schema, the description is complete: it explains when to use it, what to expect in the response, error handling, and rate limits. No critical gaps remain.

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

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

The input schema covers the single parameter 'defense_id' comprehensively with examples and format hints (100% coverage). The description only references 'slug' indirectly in the 404 sentence, adding no substantial semantic detail beyond what schema already provides.

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

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

The description clearly states 'Look up a MITRE D3FEND defense technique' using a specific verb and resource. It distinguishes itself from sibling tools by advising 'Use after d3fend_defense_search for the full record + ATT&CK chain', making the lookup's role distinct.

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

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

The description gives explicit sequencing guidance ('Use after d3fend_defense_search') and notes the 404 error on missing slugs, which helps agents decide when to call it. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals important behaviors: default SLIM response dropping uri, rate limits (Free: 30/hr, Pro: 500/hr), the exact return format, and the effect of include='full'. This adds substantial context not available from annotations alone.

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

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

The description is dense but every sentence contributes: search purpose, default output behavior, exclude_id usage, example query, drill-down pointer, rate limits, and return shape. It is front-loaded with the primary action and structured logically, earning its length.

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

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

Given the tool's 6 optional parameters and existing output schema, the description covers all necessary aspects: filtering options, output modes, rate limits, chaining behavior, and a concrete usage example. It even documents the return structure despite the output schema existing, providing complete guidance.

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

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

The schema already has 100% parameter coverage, but the description boosts understanding by explaining the rationale for include ('saves ~60 chars/row'), the chaining use of exclude_id, and giving a worked example (tactic=Harden + artifact='Access Token'). It clarifies when 'uri' appears in results.

Input schemas describe structure but not intent. Descriptions should explain 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 MITRE D3FEND catalog by keyword, tactic, or artifact, and provides a concrete example ('what defenses harden access tokens?'). It distinguishes itself from d3fend_defense_lookup by positioning it as the discovery search that returns defense_ids for later 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 explicitly states when to use the tool ('Use to discover defenses applicable to a given threat model') and names the alternative for drill-down ('Drill into d3fend_defense_lookup with any returned defense_id'). It also explains the chaining use case for exclude_id, giving clear when-to-use guidance.

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

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

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds valuable behavioral context: TXT records are returned raw with an honest count, and rate limits (Free 30/hr, Pro 500/hr) are disclosed. This exceeds the baseline expected from annotations alone.

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

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

The description is a single, dense paragraph with no wasted words. Every clause adds value: use cases, alternative tool, TXT nuance, rate limits, and return structure. It is well-structured and front-loaded with the primary 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 simple single-parameter tool with output schema and thorough annotations, the description covers all essential aspects: purpose, usage boundaries, rate limits, and return shape. It is complete for an AI agent to select 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?

The input schema already fully describes the domain parameter with format guidance and examples, achieving 100% schema coverage. The description adds no new semantic meaning for the parameter itself, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource ('Query all DNS record types') and enumerates the exact types (A, AAAA, MX, NS, TXT, CNAME, SOA). It also distinguishes itself from the sibling tool domain_report, which is referenced for a full 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 lists when to use the tool (mail routing inspection, nameserver verification, SPF/DMARC checks) and when to use an alternative (full overview via domain_report). It also provides a nuanced TXT filtering behavior distinction, giving concrete guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, establishing a safe read-only profile. The description adds valuable behavior beyond annotations: default TXT filtering, honest pre-filter count, next_calls chain logic, conditional emission of ssl_check/tech_fingerprint, and rate limits. No contradiction.

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

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

Description is well-structured and front-loaded with the core purpose. Each of the five sentences serves a distinct role: purpose, filtering semantics, usage alternative, next_calls guidance, and return summary. No wasted words for a tool with this 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 and the presence of an output schema, the description covers all necessary context: return categories (DNS, WHOIS, SSL, risk score, etc.), next_calls chaining, default filtering behavior, and rate limits. It is complete for an agent to select and invoke the tool without additional clues.

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

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

Schema description coverage is 100% and both parameters are richly documented in the input schema (e.g., include_all_txt's default filter, total_txt_records behavior, and vendor-verification stripping). The tool description largely restates these same details without adding new meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool's function: 'Query DNS, WHOIS, SSL, subdomains, and threat intel for a domain in one call.' It distinguishes itself from siblings by positioning as an all-in-one starting point and explicitly contrasts with audit_domain for live headers and tech stack.

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

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

Provides explicit usage context: 'Use as a starting point for domain investigations; use audit_domain for live headers + tech stack.' Also explains when to set include_all_txt=true and how to chain next_calls with subdomain_enum, ssl_check, and tech_fingerprint. This is concrete when-to-use vs. alternative guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context such as rate limits (Free: 30/hr, Pro: 500/hr) and the return shape ({disposable, domain, provider}), which goes beyond the annotations. No contradictions.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidance, companions, rate limits, and return format. Slightly long but every sentence adds value, and no fluff is present.

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

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

The description is complete for an agent to select and invoke: it explains what the tool does, when to use it (and when not), provides alternatives, mentions rate limits, and states the return fields. The input schema fully covers the parameter, and the output schema is mentioned even though it exists.

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

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

Schema coverage is 100% with parameter descriptions and examples. The tool description does not add additional parameter semantics beyond the schema, but the schema already fully covers the 'email' parameter, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Check if email address uses a known disposable/temporary provider' with specific examples. It also distinguishes itself from related tools like threat_intel and email_mx, making it easy to select.

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

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

Explicit usage guidance is provided: 'Use for input validation to detect throwaway signups; for domain reputation use threat_intel.' It also names companion tools with their specific purposes, giving clear when-to-use and 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?

Goes far beyond the read-only annotation by explaining the honest DKIM evidence policy (verified only if a selector responds, else unverifiable), the grading logic's dependence on DKIM verifiability, and that DKIM absence is not penalized. This prevents misinterpretation of results. Rate limits are also disclosed.

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

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

The description is dense and front-loaded with the core purpose, then adds necessary detail on DKIM semantics, grading rules, and return structure. It is somewhat long but every sentence carries distinct value; the semicolon-separated lists keep it readable. Not overly verbose for the complexity.

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

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

Covers the return object shape, the DKIM evidence edge case, the grading algorithm in detail, rate limits, and directs to a more comprehensive sibling. With an output schema present, the description still adds substantial context, making the tool fully self-contained for an agent.

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

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

The single parameter 'domain' is already fully described in the schema with examples. The description adds no new parameter syntax or constraints, so baseline 3 is appropriate given 100% 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 states a specific action ('Analyze email security') followed by the exact resources analyzed (MX, SPF, DMARC, DKIM, provider, grade). It names sibling tool domain_report to draw the boundary, making its purpose unambiguous.

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

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

Explicitly states when to use it ('verify email-auth setup and phishing risk') and directs users to domain_report for a full audit. Also includes rate-limit context, helping agents decide whether to call it under resource 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 indicate read-only, idempotent, non-destructive behavior, and the description adds significant extra context: it is passive DNS-only (no SMTP probe), DKIM probing tests common selectors and recent dates, custom selectors must be supplied, and there are rate limits (30/hr free, 500/hr Pro). These details help the agent understand side effects, constraints, and operational limitations beyond the annotations.

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

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

The description is information-dense and front-loaded with the primary purpose, then usage, scoring details, probing behavior, and rate limits. It is slightly longer than necessary but every sentence contributes meaningful information. No fluff, though the run-on structure could be improved for readability.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers the main purpose, protocols, scoring scale, probing behavior, passive nature, and rate limits. It is complete for an agent to understand what the tool does, how it behaves, and what parameters to supply. The description also helps differentiate it from numerous sibling security tools.

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

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

The schema already covers both parameters well (100% coverage). The description enhances the 'selectors' parameter by explaining that it supplies custom DKIM selectors and that probing defaults to common selectors with recent dates. This gives the agent insight into how the parameter is used and what happens if omitted, adding value beyond the schema descriptions.

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

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

The description clearly states the tool analyzes email authentication posture (SPF, DMARC, DKIM) and produces a numeric score and findings. It specifies the resource (domain) and the specific protocols, and distinguishes itself from sibling tools like email_mx or email_verify by focusing on authentication posture. The dual-use framing (red-team/blue-team) further clarifies its purpose.

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

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

The description provides clear context for when to use the tool: for red-team spoofing feasibility and blue-team posture audits. It does not explicitly name alternative tools or state when not to use it, but the context is enough for an agent to decide in most scenarios. The sibling tool list shows related tools, but the description itself doesn't draw explicit comparisons.

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

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

Beyond the readOnly/idempotent annotations, the description adds concrete behavioral details: how role_address is detected (admin@, info@), that Gmail-style +tag is stripped before classification, free_provider semantics for B2B detection, rate limits (30/hr free, 500/hr Pro), and the ethical decision to omit mailbox enumeration. This provides a full transparency picture without contradicting annotations.

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

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

The description is information-dense but every clause serves a purpose: functionality, usage timing, exclusions, behavior details, rate limits, and return fields. It is front-loaded with the main purpose and flows logically, earning a high score for efficiency and structure.

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

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

Given the tool has one parameter and an output schema (which covers return values), the description covers all necessary context: when to use, what it does, what it deliberately excludes, rate limits, and the exact output fields. No critical gaps remain for an agent to correctly select and invoke the tool.

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

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

The schema already fully documents the 'email' parameter with examples and the requirement for '@'. The description adds a bit of behavior context (e.g., +tag stripping) but does not fundamentally add new parameter-level semantics beyond what the schema provides. With schema coverage at 100%, the baseline of 3 is appropriate.

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

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

The description immediately states the tool validates emails by combining syntax checks, MX records, disposable detection, role-address detection, and free-provider classification. It explicitly distinguishes itself from sibling tools by noting it replaces email_mx + email_disposable + manual role parsing, making the purpose highly 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 gives clear usage contexts: 'Use BEFORE adding an email to a contact list, sending an outbound message, or auditing a lead-list dump.' It also explicitly states what the tool does NOT do (SMTP RCPT TO deliverability probing) and points to alternative external services for that case, providing both when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses critical behaviors: result capping (SHODAN_REFS_LIMIT default 200), the truncated flag, the honest upstream count, and deliberate avoidance of blind emission of pivots that lack schema support. This adds substantial value and does not contradict annotations.

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

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

The description is longer than average but every sentence contributes functional information: source composition, usage context, caveats, next_calls behavior, and return structure. It is front-loaded with the core purpose and remains structured, though it could be slightly tightened without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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—three data sources with differing behaviors, a truncation mechanism, and next_calls integration—the description addresses all essential aspects: return fields, limit semantics, pivot logic, and caveats about missing schema fields. It is fully self-sufficient for an agent to select and invoke correctly.

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

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

The input schema already provides a full description for cve_id with format examples, so schema coverage is 100%. The tool description does not add any new parameter-level meaning beyond what the schema states, but it does not need to; the baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Search') and resource ('public exploits/PoC for a specific CVE') and immediately distinguishes itself from siblings by enumerating three distinct data sources. It clearly states the tool computes exploit availability, differentiating it from cve_lookup, cwe_lookup, and kev_detail.

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

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

Explicit usage guidance is provided: 'Use to assess if a vulnerability has weaponized exploits in the wild; run after cve_lookup to evaluate real-world risk.' It also names alternative/complementary tools (kev_detail, cwe_lookup) and describes their pairing conditions, plus rate limits for free and Pro tiers.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds substantial context: 'no LLM is queried, fully deterministic', robots.txt honoring with 'Disallow: /' returning 403, cache-control handling, rate limits, and specific error returns (502 on DNS/TCP/TLS). This goes well beyond the annotations.

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

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

The description is long but well-structured and front-loaded with the core purpose. It packs essential details (scoring rules, ethical behavior, output fields) into a logical flow. Minor redundancy like 'we do NOT crawl' appears, 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?

The description covers purpose, methodology (7 weighted rules), ethical constraints, throttling, error handling, and the full return object. Combined with rich annotations and an output schema, it provides all necessary context for an agent to select and invoke the tool correctly.

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

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

The sole parameter 'domain' is fully described in the input schema (100% coverage), including format ('No scheme, no path, no port') and behavior ('fetches https://<domain>/ with HTTP fallback'). The tool description does not add significant new parameter-level information, 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 it performs a 'deterministic GEO / AI-visibility readiness audit of a domain's homepage' with a '0-100 score + missing_signals fix list'. It differentiates from siblings by emphasizing 'structural signals ONLY' and 'homepage-only', which distinguishes it from general SEO audits or domain reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'triage why a brand is absent from AI recommendations', 'pre-flight before GEO/AEO content work', and 'score a prospect's AI-readiness'. Constraints like 'Strictly homepage-only — we do NOT crawl' signal when not to use, but no alternative tool names are explicitly mentioned, leaving a minor gap.

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

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

Annotations already declare this as readOnly and idempotent, and the description adds valuable context: v2 vectors are rejected with a 400 status, rate limits (Free: 30/hr, Pro: 500/hr) are stated, and the detailed return structure is outlined. It does not disclose error handling beyond v2 rejection, but the provided extras go beyond the annotations.

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

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

The description is lengthy but well-structured and front-loaded with the core purpose. It packs substantial detail (output fields, usage, limitations, rate limits) without fluff. The density is high but each sentence earns its place, so it is concise in content despite its length.

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

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

The description covers input requirements, output structure, error behavior for unsupported vectors, rate limits, and guidance for both parsing and verification use cases. Given the complexity of CVSS parsing and the rich output schema mentioned, this description is complete enough for an agent to select and invoke the tool effectively without additional external knowledge.

Complex tools with many parameters or behaviors need more documentation. 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 description for 'vector' already covers the parameter fully (coverage 100%), including the rejection of v2 vectors. The tool description repeats this information and adds an example, but does not fundamentally enrich the parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Parse a CVSS v3.x vector string into a per-metric breakdown plus a recomputed base score.' This clearly distinguishes the tool from siblings like cve_lookup or calculate_risk_score, which handle different aspects of vulnerability 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?

Explicit guidance is provided: 'Use to translate raw CVSS strings into agent-friendly attributes without re-parsing the vector grammar yourself, and to verify upstream NVD scoring against the recomputed value.' It also names an alternative for v2 vectors: 'read cvss_v2_vector from cve_lookup if you need v2 detail.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description complements this by adding the data source (MalwareBazaar), rate limits (Free/Pro hourly), and the return structure. It does not contradict annotations, and provides helpful 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?

The description is compact yet information-dense: source, purpose, usage guidance, companions, rate limits, and return fields are all covered in two sentences plus a struct. Every sentence serves a distinct function with no fluff or redundancy.

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

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

The tool is simple (one parameter, output schema present), and the description covers the key aspects: what it queries, what it returns, when to use it, rate limits, and relationships to siblings. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with the file_hash parameter fully described (accepted formats, character lengths, lowercase hex, example). The description adds no new parameter-level information beyond what the schema already 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 tool queries MalwareBazaar for file hashes and lists the specific return fields (malware family, file type, size, etc.). It explicitly differentiates from sibling tools like ioc_lookup by noting the alternative for auto-detection of all IOC 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?

Provides explicit guidance: 'Use to check if file hash is known malware; use ioc_lookup for auto-detection of all IOC types.' It also names companion tools (threat_intel, exploit_lookup) and their distinct purposes, leaving no ambiguity about when to choose this 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by explaining auto-detection of IOC type, per-type source coverage (e.g., hash → ThreatFox only), and the presence of sources_queried and sources_unavailable fields to signal what actually ran. No contradictions detected.

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

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

The description is longer than average but every sentence contributes new information: source coverage, alternative tools, rate limits, and return shape. It is front-loaded with the core purpose, then expands into details, making it efficiently scannable despite density.

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

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

This is a multi-source enrichment tool with no output schema to fall back on, but the description covers types, sources, failure handling (sources_unavailable), rate limits, and alternatives. It also mentions the return fields (indicator, type, threat_level, sources, summary, verdict), making it fully self-contained for an agent to select and invoke correctly.

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

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

The schema already documents the single 'indicator' parameter with examples, so the baseline is 3. The description adds significant semantic context: auto-detection, per-type source coverage, and the meaning of verdict fields, which clarifies not just the parameter format but how the tool interprets it.

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

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

The description opens with a specific verb + resource ('Enrich Indicator of Compromise') and enumerates accepted types (IP/domain/URL/hash). It also explicitly differentiates from sibling tools by naming threat_intel and hash_lookup as alternatives, making its role clear.

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

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

The description states when to use this tool ('primary IOC triage tool when type unknown') and when not to, recommending threat_intel for domain-only and hash_lookup for richer MalwareBazaar data. It also provides rate limits (30/hr free, 500/hr Pro), giving concrete context for invocation.

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

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

Despite annotations already marking readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: the v1.16.0 breaking change in vulns format, the two-tier cloud_provider detection logic, null-explicit field behavior, the meaning of tor_exit=false in relation to sources_unavailable, and conditional next_calls. This goes far beyond what annotations convey.

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

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

The description is dense but well-organized, front-loading the core purpose and then layering important details like version changes, detection logic, and rate limits. It is a single large paragraph and could benefit from bullet points, but every sentence carries meaningful information without redundancy.

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

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

For a tool with one parameter and a rich output schema, the description thoroughly explains the return fields, null-explicit behavior, edge cases (e.g., unknown CVEs, fetch failures), and conditional next_calls. It even clarifies tier-dependent reputation sources. No significant gaps remain.

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

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

The single parameter 'ip' is fully described in the schema (100% coverage) with type and examples. The description adds no extra parameter-specific syntax or constraints, but since the schema already covers it, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Query comprehensive IP intelligence' and enumerates the exact data types (reverse DNS, ASN, ports, vulnerabilities, etc.), making its scope unmistakable. It also differentiates from the sibling tool threat_report by explicitly stating 'for orchestrated IP+reputation use threat_report,' and references next_calls to related 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?

It gives an explicit usage directive: 'Use for IP investigation; for orchestrated IP+reputation use threat_report,' naming the alternative tool. It further clarifies tier-based behavior (Free vs Pro) and rate limits, helping the agent decide when and how to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds valuable behavior beyond that: states 404 behavior, explains date_removed is null while active, and clarifies updated_at as 'our DB sync freshness'. 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 a dense paragraph but every sentence adds value—field semantics, usage direction, and rate limits. It is front-loaded with the primary purpose in the first sentence. Slightly longer than strictly necessary, but efficient overall.

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

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

Given the tool's complexity (many return fields, conditional null values, 404 behavior, integration with sibling tools) and the presence of an output schema, the description covers all essential aspects: what it returns, how it behaves on missing CVEs, and when to use it. 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?

There is only one parameter, cve_id, and the schema already provides a full description with format and examples (CVE-2021-44228). The description adds no additional semantics beyond what the schema covers, so the baseline 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 opens with 'Look up CISA KEV (Known Exploited Vulnerabilities) full record for a CVE', which is a specific verb+resource combination. It explicitly distinguishes from sibling tools by stating 'use cve_lookup for non-KEV CVEs' and framing itself as a follow-up to cve_lookup or cve_search(kev=true).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Best follow-up after cve_lookup or cve_search(kev=true) when an in_kev=true CVE is identified'. It also names an alternative ('use cve_lookup for non-KEV CVEs') and suggests chaining with cwe_lookup. Rate limits ('Free: 30/hr, Pro: 500/hr') add operational 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 readOnly, openWorld, idempotent, non-destructive, but the description adds unique behavioral context: k-anonymity via 5-char prefix (full hash never leaves tool), no data stored, and rate limits. This informs privacy and quota implications beyond the structured 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?

Three concise sentences pack purpose, usage, companion tools, rate limits, and return format with zero redundancy. Front-loaded with the core operation, making it skimmable.

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

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

With a single parameter, full schema description, output schema present, and rich annotations, the description is complete for an agent: it explains privacy, quotas, sibling differentiation, and expected return shape. No gaps for this tool's complexity.

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

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

Schema has 100% coverage with a fully descriptive sha1_hash parameter (format, example). The description reinforces the prefix-only behavior but doesn't add new syntax or edge-case semantics; per rubric, baseline 3 since schema covers it.

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

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

The description opens with a specific verb-object pair ('Check if SHA-1 hash appears in HIBP breach dataset') and immediately distinguishes the namespace from sibling 'hash_lookup' by noting different namespace. It clearly states the tool's scope (password breach audits) and uses the HIBP dataset, setting it apart from OSINT tools.

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

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

Explicitly states when to use ('password breach audits') and provides companion tool guidance: hash_lookup for file-hash malware family, email_disposable for throwaway-mail signals, username_lookup for social-platform exposure. Also includes rate limits (30/hr free, 500/hr Pro) which help the agent decide if the 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?

The description discloses the nuanced logic of is_malicious, staleness, historical record retention, rate limits, and the meaning of threat_level. This goes well beyond the annotations, which only indicate read-only safe operations.

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

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

The description is dense but not bloated; each sentence contributes essential behavioral or usage context. The return field list is somewhat redundant given the output schema, but the overall structure is well-organized and front-loaded with the primary purpose.

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

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

For a one-parameter tool with rich annotations and an output schema, the description is exceptionally complete. It explains the matching logic, staleness, rate limits, and alternative tools, leaving little ambiguity for an agent to invoke it correctly.

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

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

The input schema already covers the single 'url' parameter 100%, so baseline is 3. The description adds semantic meaning by explaining exact URL matching versus host-based checks and how the parameter feeds into the URLhaus logic, which is valuable context beyond the schema.

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

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

The description clearly states it queries URLhaus for a specific URL and its host, with a specific verb and resource. It explicitly distinguishes itself from sibling tools by naming threat_intel for domain-level checks and ioc_lookup/hash_lookup as alternatives.

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

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

The description explicitly says 'Use for URL-level threat assessment; use threat_intel for domain-level checks' and lists companion tools with their purposes. This gives clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnly/idempotent behavior, but the description adds substantial behavioral detail beyond that: carrier is omitted from the wire for MNP-restricted regions, carrier_status must be read to distinguish 'known' from 'unsupported_region', and explicitly warns not to infer the number lacks a carrier. This is valuable, non-obvious behavior.

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

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

The description is dense and front-loaded with purpose, then expands into use case, format, companion tools, rate limits, return shape, and an important edge case. Every sentence earns its place, though it is somewhat long. A tight, well-structured description.

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

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

For a tool with one parameter and an output schema, the description covers return fields, edge cases (carrier omission, carrier_status semantics), rate limits, and usage context. The carrier_status nuance is essential for correctly interpreting results and is fully explained.

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

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

Schema covers 100% of the single parameter (number) with format and examples. The description repeats the E.164 requirement but adds no new syntax or nuance beyond what the schema already provides. Baseline 3 applies since 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 opens with a specific verb ('Validate and analyze') and resource ('phone number'), then enumerates attributes (country, region, carrier, line type, timezone, formatted versions). It distinguishes itself from sibling OSINT tools by framing it as a phone-specific lookup and referencing companion tools.

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

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

States explicit use cases: 'verify phone legitimacy and detect fraud risks.' Mentions companion tools (username_lookup for social-platform handle correlation, email_disposable for throwaway-mail signal) as alternatives, giving the agent clear guidance on when to choose this tool over related ones. Also includes rate limits.

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

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

The description discloses extensive behavioral traits: SSRF-guarded target validation, 10-hop limit, loop_detected flag, truncated flag, per-target eTLD+1 throttle, rate limits (30/hr free, 500/hr Pro), and specific error responses (502, 429 with Retry-After). This goes well beyond the annotations which only specify readOnly, idempotent, openWorld, and non-destructive flags.

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

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

The description is dense but every sentence contributes concrete information—behavioral constraints, rate limits, return fields, and error cases. It is well-structured with the main action first, followed by use cases and edge-case details, though it is long.

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

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

The description is complete for a network analysis tool: it covers return fields, edge cases (loop, truncation), safety mechanisms (SSRF guard), rate limits, and error responses. Given the rich annotations and output schema, no critical context is missing.

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

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

The input schema already provides a thorough description for `url`, giving 100% coverage. The tool description adds extra practical guidance ('Pass the URL exactly as you'd curl -L it'), enhancing the schema without redundancy. This warrants a 4 rather than the baseline 3.

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

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

The description opens with a specific verb and object ('Walk an HTTP redirect chain hop-by-hop') and details use cases (URL shortener deobfuscation, phishing investigations) that clearly distinguish it from sibling tools like DNS lookup or IP 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 explicitly states when to use the tool with three concrete scenarios (bit.ly/t.co/lnkd.in deobfuscation, phishing link audit, marketing tracking). However, it doesn't mention when not to use it or alternatives, so it falls short of a 5.

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

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

The description adds substantial behavioral detail beyond the readOnly/idempotent annotations: the ContrastAPI user-agent string, honoring Disallow for internal tools, per-eTLD+1 throttling at 60 req/min, free/pro rate limits, and 502 error semantics. This level of transparency helps agents anticipate side effects and 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?

Although the description is long, it is dense with non-redundant, operationally critical information: usage context, HTTP fallback, 404/502 semantics, UA identification, throttle, and rate limits. Every sentence earns its place and the main purpose 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?

Even with an output schema present, the description explains return fields, error responses, and failure modes. It covers edge cases (404 vs 502), rate throttling, and relation to sibling tools, making the tool fully self-sufficient for correct invocation and interpretation.

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

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

The input schema already documents the single `domain` parameter with 100% coverage, including 'No scheme, no path, no port' and subdomain handling. The description adds no new parameter-level meaning; it stays at the baseline of relying on the schema.

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

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

Description starts with 'Fetch + parse the target domain's robots.txt' and enumerates exactly what it returns (sitemaps, allow/disallow rules, crawl-delay, Host). This clearly distinguishes it from siblings like dns_lookup or seo_audit by naming a unique resource and action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 BEFORE crawling/scraping a target site (seo_audit, brand_assets, redirect_chain) to honour the site's published rules.' It also provides an exclusion: 502 means upstream failure, not 'no robots', and explains when no robots.txt exists (404 → allow-all). This is textbook 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behavioral details: header values are truncated to 500 chars by default, and include='full' restores the full raw value (with a note about large CSP headers). It also states the exact return object shape. This gives the agent actionable knowledge about result fidelity and option effects.

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

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

The description is compact yet information-dense. It opens with an immediate statement of purpose, then lists checkable headers, usage context, an alternative, rate limits, a behavioral caveat, and the return format. Every sentence earns its place and there is no fluff.

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

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

Despite the tool's moderate complexity, the description covers purpose, usage, alternatives, performance characteristics (rate limits), output structure, and a detailed behavioral nuance (truncation). An output schema exists, so return fields are further documented. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already covers 100% of the parameters with highly detailed descriptions, including the exact behavior of include. The tool description restates some of this (e.g., 'pass include=full') but adds no new semantic meaning beyond what the schema provides. Per the rubric, with high schema coverage, 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 that the tool performs a live HTTP GET and analyzes security headers, listing the specific headers checked (CSP, HSTS, etc.). It also distinguishes itself from the sibling check_headers by noting that scan_headers audits live websites while check_headers validates existing headers. This is a specific verb+resource with explicit sibling differentiation.

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

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

The description explicitly tells the agent when to use this tool ('Use to audit live website headers') and provides an alternative ('use check_headers to validate headers you already have'). It also includes rate limit information (Free vs Pro), giving concrete guidance on practical 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by disclosing robots.txt honoring (`Disallow: /` returns 403 `robots_txt_disallow` and skips the fetch), cache write behavior (`Cache-Control: no-store`/`private` sets `cache_respected=false`), per-target eTLD+1 rate limiting (60 req/min), and the `_untrusted` suffix on target-derived data. These operational details are not in annotations and greatly inform safe usage.

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

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

The description is long but each sentence earns its place: it front-loads the core purpose and output, then packs in usage context, audit rules, behavioral constraints, rate limits, and return fields. The structure is logical and dense without padding, making it an efficient reference for an AI agent.

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

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

The tool is complex with many edge cases (robots.txt, caching, rate limits, untrusted data), and the description covers all of them explicitly. Error conditions (502 on DNS/TCP/TLS failure, 403 `robots_txt_disallow`) are enumerated, and the comprehensive return field list is provided even though an output schema exists. No critical context is missing for safe and 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 100% coverage for the single parameter `domain`, including 'Registrable domain... No scheme, no path, no port. Strictly homepage-only — the bot fetches https://<domain>/ with HTTP fallback.' The description reinforces this but adds no new parameter-specific semantics beyond the schema. Baseline 3 is appropriate given full 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 performs a 'One-shot SEO audit of a domain's homepage' and produces a 0-100 composite score plus a `missing_signals` list of fixes. This specific verb+resource combination (audit homepage, score, fixes) distinguishes it from sibling tools like `audit_domain`, `domain_report`, or `geo_audit` by emphasizing SEO focus, homepage-only scope, and the scoring mechanism.

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

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

Explicit usage guidance is provided: 'Use BEFORE pitching SEO work to a prospect, when triaging a lead's marketing maturity, or as a structured pre-flight before deeper auditing tools (Lighthouse / SEMrush).' It also explicitly states 'Strictly homepage-only — we do NOT crawl the site,' which differentiates it from crawler-based tools and sets clear expectations for when to use this lightweight audit.

Agents often have multiple tools that could apply. Explicit usage 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 annotations already declaring read-only, idempotent, and non-destructive, the description adds substantial behavioral context: data refresh schedule (daily at 02:00 UTC), rate limits (Free/Pro), and the shape of the response including next_calls suggestions. This goes beyond the annotations and fully informs the agent.

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

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

The description is dense but every sentence earns its place: purpose, return contents, use cases, follow-ups, rate limits, and response shape. It is well-structured and front-loaded, with no redundancy.

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

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

For a lookup tool with a rich output schema, the description covers the lookup target, return payload, usage context, rate limits, and related follow-up tools. It is complete enough for an agent to decide when and how to invoke this tool, and what to expect in response.

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

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

The input schema already documents rule_id with type, format, example, and source (REST sigma_rule_search), so coverage is 100%. The description reinforces that the rule is a UUID and mentions the source, but adds no new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool performs a lookup of a single Sigma detection rule by UUID, explicitly naming the resource (SigmaHQ corpus) and differentiating from bulk operations via the word 'single'. It also enumerates returned fields, making the purpose unmistakable.

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

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

The description provides explicit use cases: fetching a known rule for context or inspecting a rule found via REST sigma_rule_search. It also mentions natural follow-up lookups. However, it does not explicitly mention when NOT to use it (e.g., when needing multiple rules, use bulk_sigma_rule_lookup), so clear exclusions are missing.

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

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

Beyond readOnlyHint and idempotentHint, the description explains nuanced behavior: invalid certs are delivered as valid=false + validation_errors[] rather than failures, and clarifies the grading semantics (D vs F). This gives operational insight annotations alone cannot convey.

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

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

The description is dense but well-structured: purpose, edge-case behavior, grading definition, usage note, rate limit, and return format. While every sentence adds value, it is slightly longer than strictly necessary; a tighter rendition could push it to 5.

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

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

Given the tool's single simple parameter and the presence of an output schema, the description covers all essential operational aspects: what it returns, how invalid certs are handled, the meaning of grades, and when to use it. Nothing important is omitted.

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

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

The only parameter, domain, is fully described in the schema (100% coverage) with examples. The description adds no additional parameter-level semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with 'Analyze SSL/TLS certificate', a specific verb+resource, and lists concrete outputs (grade, protocol, cipher, etc.). It distinguishes itself from sibling tool audit_domain by explicitly noting 'for full domain audit use audit_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?

Provides explicit when-to-use guidance: 'Use to audit certificate validity and detect expiring certs', and explicitly points to an alternative tool for broader audits. Also includes practical rate limit context (Free 30/hr, Pro 500/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 annotations already indicate readOnly/idempotent/non-destructive, but the description adds crucial behavioral context: wildcard_status interpretation (absent/present/undetermined), crtsh_status handling (timeout/rate_limited/unavailable/error), and next_calls cap. This explains how to interpret potentially misleading counts, far exceeding the structured annotations.

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

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

The description is long but well-structured: purpose is front-loaded, followed by usage, rate limits, output fields, and detailed status logic. Every sentence serves a purpose, though some redundancy with the output schema could be trimmed; still, it's concise enough for the complexity it covers.

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

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

Given the tool's complexity and the presence of an output schema, the description fully covers edge cases like wildcard DNS and CT service failures, and explains how to interpret counts. It even warns against inferring low exposure from wildcard-present results, making it complete for an agent to use 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 schema covers the single 'domain' parameter at 100% with its own description, and the tool description does not add extra parameter-level meaning. Baseline applies since schema does all the heavy lifting; no additional format or constraint details are provided.

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

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

The description states 'Discover subdomains using passive methods: Certificate Transparency logs + DNS brute-force (no active probing)' with a clear verb and resource. It further distinguishes for attack surface mapping, separating it from sibling tools like dns_lookup or ssl_check.

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

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

Explicitly says 'Use to map organization's attack surface; non-intrusive', giving a clear when-to-use. It also provides rate limits and next_calls usage for large enumerations, but does not explicitly name alternative tools or state exclusions, so it lacks explicit when-not 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, idempotent, and non-destructive behavior, the description adds valuable behavioral context: it specifies the mechanisms (HTTP headers + HTML analysis), emphasizes passive reconnaissance, and discloses rate limits. No contradictions with annotations.

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

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

The description is concise, front-loaded with the core purpose, and includes only high-value details: what it detects, how it detects, usage guidance, rate limits, and the return format. No redundant or filler content.

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

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

For a single-parameter tool with an output schema and strong annotations, the description is exceptionally complete. It includes the output shape, alternative tools, rate limits, and methodology, leaving no significant gaps for an agent to infer correctly.

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

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

The input schema already provides a clear description for the single 'domain' parameter with examples ('example.com', 'shopify.com'). The description does not add meaningful extra parameter semantics beyond that, so the baseline score of 3 applies due to 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: detecting website technology stack (CMS, frameworks, CDN, analytics, web servers, languages) via HTTP headers and HTML analysis. It explicitly lists the categories of technologies detected, distinguishing it from sibling tools like check_headers (header-only) and audit_domain (full audit).

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

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

The description explicitly says 'Use for passive reconnaissance' and directs users to 'audit_domain' for full audits, providing a clear alternative. It also includes rate limit information (Free: 30/hr, Pro: 500/hr), which helps set expectations for 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=true and idempotentHint=true, and the description consistently aligns while adding substantial context: it specifies data is sourced from local DB mirrors (no Shodan/AbuseIPDB), the CVE batch size is 50, costs 10 tokens per call, and lists exact return fields. This goes well beyond the annotation baseline.

Agents need to know what a tool does to the 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 begins with the tool's composite nature, then lists steps, tier behavior, batch size, cost/rate, and return structure. Every sentence carries meaningful information with no filler, making it appropriately sized for a complex composite 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?

For a tool with this complexity—composite logic, multiple outputs, and operational constraints—the description is exceptionally complete. It covers data sources, tier behavior, cost/rate limits, batch size, and return fields. The presence of an output schema reduces the need to explain returns, yet the description still does so, 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?

The single parameter 'domain' is already fully described in the schema, including an example and rejection of IPs/internal hostnames. The description does not add additional semantic detail about the parameter beyond what the schema provides, so the baseline of 3 applies due to 100% 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 opens with 'Composite tech-stack + CVE audit' and precisely enumerates the steps: technology detection, CVE querying, KEV enrichment, and exploit/PoC checks. This clearly identifies the tool's specific purpose and distinguishes it from sibling tools like cve_lookup or tech_fingerprint by highlighting the composite nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 strong contextual guidance, stating the tool is MCP-only, has no tier gating, and details cost/rate limits (e.g., Free 30/hr ≈ 3 audits). It clarifies when the tool is relevant—when a combined tech-stack and CVE audit is needed—but does not explicitly name alternatives or state 'use X instead when...'.

Agents often have multiple tools that could apply. Explicit usage 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, etc.), the description adds context about rate limiting (30/hr vs 500/hr), single-source behavior, and the exact return fields. This is useful behavioral disclosure without contradicting the annotations.

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

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

Four sentences, each carrying distinct value: purpose, source, guidance, rate limits, and return shape. No redundant phrases and front-loaded with the core action.

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

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

With a single parameter, rich annotations, and an output schema present, the description covers purpose, alternatives, rate limits, and return fields. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% and the schema already clearly explains the 'domain' parameter. The description adds no extra parameter-level semantics beyond what the schema contains, 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?

Clearly states the tool checks a domain against abuse.ch URLhaus for known malware-distribution URLs. It distinguishes itself from siblings by explicitly mentioning ioc_lookup and phishing_check as alternatives.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'single source' for fast domain-level assessment, use ioc_lookup for multi-feed correlation, and phishing_check for specific URLs. Also gives rate limits.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial behavioral details: rate limits (30/hr free, 500/hr Pro, token cost), a breaking change in enrichment.vulns format (list[VulnInfo] vs list[str]), the asn block's 50-prefix cap, and the top-level return keys. This goes far beyond the annotations.

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

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

The description is long but every sentence carries essential operational info: core purpose, usage context, two critical caveats (asn prefix cap, vulns breaking change), rate limits, and return structure. It is front-loaded with the primary purpose and structured logically, with no wasted words.

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

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

Given the tool's complexity (multiple data sources, nested structures, version sensitivity, rate limits) and the presence of an output schema, the description covers all key operational aspects: limitations, version change, rate limit, and the shape of the return object. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The only parameter 'ip' is fully documented in the schema (data type, examples, rejection of private/reserved IPs). The description does not add any extra semantics for the parameter itself; it only reuses the concept of IP in the context of the tool. With 100% schema coverage, this is a baseline adequate score.

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

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

The description opens with a specific verb ('Query') and resource ('comprehensive threat profile for an IP'), enumerating the data sources (Shodan, AbuseIPDB, ASN/geolocation, open ports). It clearly distinguishes from siblings by explicitly pointing to domain_report for domain 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?

It states when to use ('Use for IP investigation and SOC alert triage') and provides an explicit alternative: 'for domain data use domain_report.' It also cross-references asn_lookup for full prefix lists, giving clear guidance on related tools.

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

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

Annotations already declare readOnly and idempotent behavior. The description adds concrete return structure (platform list with exists, url, status_code) and rate limits, providing valuable expectations beyond the schema. No contradictions with annotations.

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

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

Two compact sentences front-load the core action and scope, then efficiently cover use cases, rate limits, and return shape. Every sentence contributes value with no filler.

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

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

The tool is simple (one parameter) and the description provides all essential context: platforms checked, use cases, rate limits, and expected output. Even though an output schema exists, the description's return format summary adds clarity without needing more.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents the single parameter (100% coverage) including the '@' prefix rule and examples. The description adds no new parameter-specific details, so the baseline score of 3 applies.

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

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

The description opens with a specific verb ('Search') and a clear resource ('username across 15+ social/dev platforms'), listing concrete platform examples. This distinguishes the tool from sibling lookup tools such as domain_report or ip_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 explicitly states primary use cases ('OSINT investigations and identity verification') and provides rate limits, giving clear context for when to use it. It does not name alternatives, but no sibling tool overlaps in functionality, so exclusions are unnecessary.

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

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

Beyond the readOnly/idempotent annotations, the description discloses crucial behaviors: status='ok' vs 'unavailable' semantics, that total_snapshots is omitted (not zero) on failure, specific error codes in warnings[], and known heavy domains that time out. 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 relatively long but well-organized: purpose, usage, rate limits, status details, error handling, returns. Each sentence carries necessary information, though the status/error segment is dense and could be tightened slightly. Not wasteful enough for a 3, but not as minimal as a two-sentence ideal.

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

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

For a one-parameter lookup tool, the description is exceptionally complete: it covers the return structure, error states, rate limits, alternative tools, and edge cases like heavy domains and CDX timeouts. The output schema existence plus this description leaves no major gaps.

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

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

The schema already provides 100% coverage for the single domain parameter with examples. The description adds no further parameter syntax or format detail; it only references heavy domains in a behavioral context, so it neither improves nor worsens schema coverage. Baseline 3 applies.

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

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

The first sentence clearly states the tool retrieves Wayback Machine snapshots for a domain, listing specific outputs (first capture, latest, total count, snapshot list). It also explicitly distinguishes from the sibling tool by saying 'for full audit use domain_report'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 directly states when to use: 'Use to investigate domain history and age' and gives alternatives: 'for full audit use domain_report.' It also provides rate limits (Free: 30/hr, Pro: 500/hr) and fallback guidance for heavy domains.

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