Blackveil DNS

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v3.64.0
Disambiguation4/5
Most tools have distinct purposes with clear descriptions, but the high number (80) and some similar functions (e.g., check_rbl vs check_mx_reputation, multiple OSINT start tools) create potential confusion. Async variants of brand and OSINT tools are well-differentiated.
Naming Consistency5/5
All tools follow a consistent verb_noun snake_case pattern (check_, scan_, discover_, etc.) with no mixed conventions. Even special cases like 'cymru_asn' and 'rdap_lookup' fit the pattern.
Tool Count2/5
80 tools is excessive for a single MCP server, even for a broad domain security service. Many tools are async variants (start/status/findings) that could be consolidated, and the surface feels bloated rather than streamlined.
Completeness4/5
The tool set covers an extensive range: DNS security checks, email authentication, brand monitoring, OSINT, compliance mapping, and remediation generation. Minor gaps exist (e.g., no tool for reputation history), but overall it's thorough for the domain.
Average 4.2/5 across 80 of 80 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 12 community issues answered or closed in the last 6 months
- 357 commits in the last 12 weeks
- Last stable release on August 23, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Business Source License 1.1.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, so the description adds minimal behavioral context beyond '4 public resolvers'. It does not disclose behavior on inconsistency, caching, or resolver selection. Meets basic expectations but adds little value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It effectively communicates the core action in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 3 parameters and no output schema, the description lacks details on output format, consistency criteria, or resolver identities. This gap leaves the agent underinformed about the tool's behavior and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described in the input schema (domain, format, record_type). The description adds no additional parameter meaning, so it stays at the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Check DNS consistency across 4 public resolvers' clearly states the tool's purpose. It specifies the action (check), resource (DNS consistency), and context (across 4 public resolvers), distinguishing it from siblings that focus on specific DNS record types or security checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools for specific DNS checks (e.g., check_dnssec, check_spf), the agent lacks context on when a general resolver consistency check is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds specific context about what evidence is checked (root hints, glue, delegation, serial, DNSKEY cross-root). However, it does not describe output format, failure behaviors, or any further implications. With annotations covering safety, the description adds modest value but not extensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the core purpose without verbose or redundant language. Every word adds value, and it is front-loaded with the action and subject.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 optional parameter, full schema coverage, output schema present, and read-only annotations), the description covers the main function. However, it lacks usage guidance and does not elaborate on the evidence types beyond listing them, which might leave some ambiguity about how 'cross-root evidence' is interpreted. Since the output schema exists and annotations cover side effects, this is adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter 'format', including an enum and description 'Output verbosity. Auto-detected if omitted.' The tool description does not mention this parameter, so it adds no additional meaning beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Check the DNS root server set against official root hints, root glue, delegation, serial, and DNSKEY cross-root evidence.' It uses a specific verb (Check) and resource (DNS root server set) and specifies exactly what it validates against. This distinguishes it from sibling tools like check_ns, check_dnssec, etc., which focus on different DNS aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or contrast with sibling tools. For example, it doesn't say 'Use this when verifying root server consistency' or 'For other DNS checks, see check_ns.' The agent is left to infer usage entirely from the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context beyond those annotations by revealing the underlying BV_INFRA_PROBE dependency and the evidence categories (raw DNS, routing, RPKI, vantage-point), which helps the agent understand the tool's data acquisition behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences. The first states the purpose, the second names the key data-source detail. No filler, no redundancy, all content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to explain return values. It covers purpose, scope (authoritative DNS infrastructure), and evidence source. It is slightly less complete than ideal because it omits what the 'posture' result means or how it relates to the many sibling DNS tools, but the schema and annotations fill most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (domain, format, force_refresh) has a helpful description. The tool description adds no parameter-specific meaning, but the schema already carries that burden sufficiently, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a specific verb+resource: 'Check authoritative DNS infrastructure posture for a hostname.' This distinguishes it from sibling tools that check individual DNS records (MX, SPF, NS, etc.), though it does not explicitly name the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives. The sibling list contains numerous focused DNS checks (check_ns, check_dnssec, check_dnssec_chain), and the description could have indicated this is the comprehensive posture check while those are for specific record types, but it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read operation. The description adds valuable context: that it resolves MX hosts to IPs firstma and checks against a specific list of 7 blocklists. This goes beyond annotations but does not disclose potential rate limits or response structure. Given annotations cover safety, adding the resolution step and blocklist names is meaningful, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no filler. The second sentence adds a valuable implementation detail (MX resolution) and a concise list of blocklists. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required param, three total). The description explains the core workflow (resolve MX to IPs, check against 7 blocklists). Output schema exists, so return format is covered. It could mention if there are rate limits or failure behaviors, but for a read-only lookup with clear paramschers, this is adequate. The only slight gap is no mention of what happens if no MX records exist, but that's minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 3 parameters have descriptions). The description does not add any parameter-specific semantics beyond what the schema already provides; it only explains the overall workflow. Per rubric, baseline is 3 when coverage is high, and there's no extra value, so a 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb ('check'), resource ('MX server IP reputation'), and scope ('against 7 DNS-based Real-time Blocklists'). It clearly distinguishes from siblings like check_mx (which likely checks MX records/configuration) and check_mx_reputation (which may be similar but this tool specifies the 7 blocklists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives, nor any prerequisites or exclusions. While the description makes the function clear, it doesn't contrast with check_mx_reputation or other related tools. The user must infer when this is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. The description complements these by clarifying the tool targets mail servers and is part of an audit workflow, though it could have mentioned caching behavior (force_refresh) or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the core purpose immediately front-loaded in the first sentence and additional audit context in the second. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple DNS lookup tool with a clear schema and an output schema available, the description is adequately complete. It clearly identifies the tool's domain (mail servers) and place in the audit, though it could briefly mention that force_refresh invalidates cache to set expectations about response freshness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for each parameter (e.g., domain, format, force_refresh). The description adds no additional context beyond what the schema supplies, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Verify') and resource ('forward-confirmed reverse DNS (PTR/FCrDNS) for mail servers'). It distinguishes from numerous check_* siblings by naming the exact DNS record type and use case. The phrase 'Part of the scan_domain audit' adds scoping context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the many sibling tools like check_mx or check_spf. The only contextual hint is 'Part of the scan_domain audit,' but there is no explicit 'use when' or comparison to alternatives, leaving the agent to guess when this specific check is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only profile. The description adds context about what the audit checks for (stale entries, SaaS exposure) but does not disclose additional behavioral traits such as caching behavior, rate limits, or data sources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, 10-word sentence that is front-loaded and contains no redundant information. Every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of this read-only audit tool, the combination of a concise description, comprehensive parameter schema, and full annotation coverage provides sufficient context. The description does not explain the exact criteria for 'stale' or 'SaaS exposure', but the output schema likely covers results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a descriptive explanation (domain, format, force_refresh). The description does not need to compensate for missing schema information, and the schema fully documents parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Audit') and resource ('TXT records'), and specifies the focus ('stale entries and SaaS exposure'). This differentiates it from sibling tools like check_spf or check_zone_hygiene, which target other record types or broader zone hygiene.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for auditing TXT records but does not explicitly state when to use it over alternatives or when not to use it. No exclusions or alternative tool references are provided, leaving usage context to the user's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior knee. Description adds substantial behavioral context: it reports on DNSSEC anchoring, DANE binding trust, and capability-document integrity, and notes the use of private-use SVCB parameter codes pending IANA assignment (a caveat about potential instability). These details meaningfully exceed the annotations, so a 4 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences front-load the purpose and then list the key checks. Every sentence adds value: purpose, detection scope, and read-only note. It is not overly long, though it packs a lot of technical detail. Slightly above average due to efficiency and prioritization.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a niche protocol tool, this description covers the essential aspects: what records it looks for, what security properties it evaluates (DNSSEC, DANE, capability integrity), and the current standardization status (pending IANA). Combined with a detailed schema and output schema, an agent has sufficient context to select and invoke this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all 6 parameters (100% coverage), including format, protocol, domain, and verify_cap. The description adds some contextual nuance (e.g., 'reports whether the discovery zone is DNSSEC-anchored' ties protocol to the indexing) but largely complements the schema rather than adds new meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific, concrete language: 'Assess the security posture of IETF BANDAID agent-discovery records (draft-mozleywilliams-dnsop-dnsaid).' It names the exact resource type (SVCB agent records), the naming convention (_agents/_index._{protocol}._agents), and distinguishes itself from the generic DNS-check siblings (check_dnssec, check_dane, etc.) by focusing on a specific draft spec. Purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the specific technical context but never explicitly states when to use this tool over alternatives or when NOT to use it. It is clearly specialized for IETF BANDAID agent-discovery records, but no exclusions or comparisons to sibling tools are given. Given the niche focus, the intended use case is inferable, but explicit guidance would be stronger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. Description adds artifact types and usage but no additional behavioral details (e.g., authentication needs, rate limits, return format). Adds some value beyond annotations but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and lists types, second gives usage guidance. No unnecessary words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (5 with enums) and no output schema, description covers artifact types and usage but does not explain return values or behavior for each artifact type. Adequate for a tool with well-known artifact types, but missing detail that could aid an agent in understanding output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description lists artifact types but does not add meaning beyond what the schema already provides for each parameter. No extra context for enum values or dependencies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Generate' and resource 'DNS/email security remediation artifact', listing all six artifact types. This distinguishes it from sibling tools that perform checks (e.g., check_spf) or scans, making purpose explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when asked to generate or create a record or policy', providing clear usage context. Does not mention when not to use or name alternative tools, but sibling set (mostly check tools) makes contrast clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false, so the description doesn't need to restate these. It adds contextual behavior: 'Operator-deploy only' (access restriction) and 'degrades to info when unprovisioned or not yet complete' (fallback behavior). This goes beyond the annotations and provides useful operational insight, earning a 4 despite the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no redundant wording. It front-loads the core action and adds the key edge-case behavior in the second sentence. Every word earns its place, making it highly effective for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, no output schema), the description covers key aspects: purpose, input identifier, and degradation behavior when the investigation is incomplete or unprovisioned. It doesn't describe the report structure, but that is not required in the absence of an output schema; the phrase 'final report' is self-explanatory. It could be more complete by suggesting checking status first, but it is adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single parameter. It only mentions 'by investigationId,' which merely repeats the parameter name without adding meaning (e.g., format, source, or how to obtain a valid ID). Since it doesn't clarify the parameter's value or provide context like 'retrieve from osint_investigation_status,' the description adds minimal semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to retrieve the final report of a completed OSINT investigation, identified by investigationId. It uses a specific verb (retrieve) and resource (final report), and distinguishes it from sibling tools like osint_investigation_status (which checks status) and osint_investigate_*_start (which initiates investigations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is for completed investigations, and mentions 'degrades to info when unprovisioned or not yet complete,' hinting that the user might need to check status first. However, it does not explicitly mention alternatives like osint_investigation_status or provide clear when-to-use vs when-not-to-use guidance. The restriction 'Operator-deploy only' is a usage guideline but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations (output includes severity, feasibility, steps, mitigations). Annotations already declare readOnlyHint, idempotentHint, and no destructiveness, which align with the description. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence that front-loads the purpose and enumerates output items. It is efficient but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value content well (severity, feasibility, steps, mitigations). It misses details on caching behavior but force_refresh parameter partially covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for all three parameters. The description does not add extra meaning beyond the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes DNS posture and enumerates attack paths with severity, feasibility, steps, and mitigations. This distinguishes it from sibling tools that focus on individual checks (e.g., check_spf, check_dmarc).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for adversarial analysis but does not explicitly state when to use this tool versus running individual checks or other synthesis tools. No when-not or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it returns decoded return codes, but does not elaborate on caching, network dependencies, or error scenarios; it meets the reduced bar but adds limited extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that front-loads the core purpose and includes concrete block-list names; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete schema, comprehensive annotations, and an output schema, the description sufficiently conveys the tool's scope and result format. It could mention cache behavior or default format, but these are covered by parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Check'), a resource ('domain reputation against DNS-based Domain Block Lists'), and explicitly lists the lists (Spamhaus DBL, URIBL, SURBL), distinguishing it from sibling checks like check_rbl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool applies (domain reputation on DBLs) but does not explicitly mention alternatives or exclusion cases, such as when to prefer check_rbl for IP-based lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect behavior. The description adds some context about what it traces (DS/DNSKEY records, algorithm usage) but does not disclose additional behaviors such as caching nuances, rate limits, or what happens if the chain breaks. With annotations present, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action, and every sentence adds value. It states what the tool does and when to use it without any redundancy or filler. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only diagnostic tool with three straightforward parameters, the description is sufficiently complete. It explains the tool's scope and use case, and since an output schema exists, detailed return value explanations are unnecessary. It could be slightly more explicit about the output structure, but the description covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for domain, format (including enum), and force_refresh. The tool description does not add extra meaning beyond the schema—it only mentions 'tracing DS/DNSKEY records,' which is not parameter-specific. Given high schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Walk the full DNSSEC chain of trust from the DNS root down to the target domain') and clearly distinguishes from sibling tools like check_dnssec by focusing on the complete chain tracing behavior. It explicitly mentions tracing DS/DNSKEY records and algorithm usage, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: 'Use when asked to trace the chain of trust from the DNS root, or to see the full DNSSEC delegation path step by step.' However, it does not explicitly note when not to use it or contrast with simpler alternatives like check_dnssec, leaving some ambiguity for an agent choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral context by explaining the tool identifies mail servers and provider, and references its role in scan_domain audit. It does not disclose additional operational details like caching behavior or freshness semantics (though the force_refresh parameter implies caching), but given the strong annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no fluff. It front-loads the purpose, then provides usage guidance, then contextual placement. Every sentence earns its place, and it is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and comprehensive annotations, the description is complete for a simple DNS lookup. It explains the core function and when to use it. It could mention edge cases like missing MX records, but that is not essential given the schema and audit context. Overall, it adequately covers the necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (domain, format, force_refresh) are already well-described in the schema. The description adds minimal parameter-specific value; it only indirectly refers to domain. With full schema coverage, the baseline is 3, and the description does not surpass that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (look up MX records) and the resource (domain), and further explains what it reveals (mail servers and email provider). It also distinguishes itself from sibling DNS check tools like check_spf and check_dmarc by specifying its unique output. The mention of being part of scan_domain audit adds context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 when asked which email provider hosts inbound mail for a domain, or to see MX record configuration.' This gives clear use cases. However, it does not mention when not to use it or list alternative tools for comparison, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true, destructiveHint false, and idempotentHint true, covering the safety profile. The description adds that it analyzes the SPF include chain, which is useful behavioral context beyond annotations. No additional side effects or operational traits are disclosed, but with strong annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no filler. Every word adds value, efficiently conveying what, when, and the parent context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% parameter coverage, the description needs only to clarify the tool's niche and usage context, which it does. It might have mentioned cache behavior or return format, but those are covered by the schema and annotations. Overall, it's sufficiently complete for this simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (domain, format, force_refresh) are already well-documented with descriptions in the schema. The tool description adds no additional parameter meaning, matching the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Detect' and clearly states the resource: 'SubdoMailing risk' through analysis of the SPF include chain. It differentiates from siblings by focusing on dangling/hijackable subdomains in SPF includes, distinct from tools like check_subdomain_takeover or resolve_spf_chain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios: 'Use when you want to know if an SPF include chain can be hijacked through a dangling domain, or to detect subdomain mailing risk hidden in SPF includes.' It also notes it's part of the scan_domain audit, giving context, though it doesn't explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds no further behavioral details, such as side effects (e.g., network requests) or failure modes. It aligns with annotations but does not enhance transparency beyond what is already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no redundancy. It efficiently states the action ('Audit DNS zone hygiene'), the specific checks performed, and the intended usage. The structure is clear and directly to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool, the description is adequately complete. It covers the core functionality, key findings, and usage scenarios. It does not detail output format or limitations, but these are likely straightforward for a check tool and can be inferred. The description gives enough context for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (domain, format, force_refresh) are fully described in the schema with clear meanings (e.g., format: 'Output verbosity'). The tool description does not elaborate on these, such as what 'full' vs 'compact' output entails or when to use force_refresh. Since schema coverage is 100%, the description adds no extra parameter clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: auditing DNS zone hygiene. It specifies the types of issues it identifies (sensitive subdomains, stale SOA records, zone propagation issues) and mentions a specific use case (finding unintended public subdomains). This distinguishes it from sibling tools that focus on narrower checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage directive: 'Use to find any sensitive subdomains that should not be publicly visible, or to audit overall DNS zone cleanliness.' This tells the agent when to invoke the tool. It does not explicitly contrast with alternatives, but the scoped purpose is sufficient for typical decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and idempotentHint, lowering the bar. The description adds that it aggregates multiple signal types and that the exact seed domain must be passed verbatim, which is useful behavioral context. However, it does not disclose whether the operation is synchronous or asynchronous, or other side-channel behavior beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: purpose, when to use, and a critical usage warning. It is front-loaded with the most important information and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% coverage, enum values, 12 params) and an output schema, the description provides enough core context. However, it omits any mention of companion start/status/findings tools or whether results may be returned asynchronously, which would be helpful for a complex discovery workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with rich descriptions for all 12 parameters, so the description need not repeat them. The seed-domain instruction in the description duplicates what the domain parameter schema already says in detail, adding no additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers all domains in a brand's portfolio by aggregating certificate, DNS, redirect, and mail-policy signals. This specific verb ('discover') plus resource ('brand portfolio domains') and method distinguishes it from sibling checkers and subdomain discovery tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it when asked what domains are part of a brand portfolio or to find all domains related to a brand. It gives clear context but does not mention exclusions or alternative tools, so it stops short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint; description adds 'impact and remediation' but no additional behavioral context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that effectively communicates the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema, but description hints at return values (impact and remediation). Adequate for a simple explanation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema descriptions are adequate; description does not add extra meaning beyond what is already in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Explain a finding with impact and remediation' clearly states the verb and resource, and distinguishes it from sibling check tools which focus on specific checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives, but the purpose is clear from context as a utility tool for explaining findings after a check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond idempotent, read-only annotations: describes output (pass/fail/partial status), mentions caching behavior via force_refresh parameter, and output verbosity formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, purpose and key details front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description adequately covers output (status per control). With rich annotations and clear purpose, it is nearly complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage). The description does not add new parameter details, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it maps scan findings to compliance frameworks (NIST, PCI DSS, SOC 2, CIS) and shows pass/fail/partial status. Distinguishes from sibling tools like check_spf or scan_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for compliance assessment but does not explicitly state when to use this tool versus alternatives like individual check tools or batch scans.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable context: async behavior (returns immediately), operator-deploy restriction, degradation to info when unprovisioned, and the polling mechanism. This goes beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, operational constraint, and return/polling behavior. No fluff, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter async start tool with no output schema, the description covers the essential operational aspects: async nature, provisioning constraint, and how to retrieve results. It could mention what the investigation covers (supply-chain scope is implied but not detailed), but given the simplicity, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'query' implicitly but doesn't explain what a good query looks like, format constraints, or examples. The single parameter is simple (string, 1-253 chars), so the gap is moderate, but the description could add more guidance on query formulation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an async supply-chain OSINT investigation for a query, with a specific verb ('Start') and resource ('supply-chain OSINT investigation'). It distinguishes from siblings by naming the async pattern and the companion polling tool, though it doesn't explicitly contrast with other osint_investigate_*_start tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it's operator-deploy only, degrades to info when unprovisioned, and returns an investigationId to poll with osint_investigation_status. It doesn't explicitly state when NOT to use it or name alternatives, but the async pattern and polling instruction give adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavioral details: recursive resolution, lookup count, tree depth, and flagging of circular includes/limit exceedance. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first sentence states the primary action, the second lists key features. No redundancy or unnecessary words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (recursive resolution, flags, limits) and no output schema, the description adequately covers the core behavior. It mentions key output aspects (lookup count, tree depth, flags). Slightly missing return type hints, but sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description does not add further meaning beyond what is already in the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Trace', 'resolves', 'shows', 'flags') and clearly identifies the resource (SPF include chain for a domain). It distinguishes from sibling tools like check_spf by focusing on recursive resolution and limits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deep SPF chain analysis but does not explicitly state when to use this tool versus alternatives like check_spf or when not to use it. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive traits. The description adds valuable context about version stamps (scoringModelVersion vs dnsChecksPackageVersion independence) and instructs to record scoringConfigHash. No contradictions. It could have mentioned caching behavior (related to force_refresh) but not required given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized and front-loaded with the core purpose. The version stamp paragraph is essential to prevent misuse, so no fluff. Slightly dense but every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the key return values (score, grade, finding counts). It also covers usage distinctiveness and the version gotcha. Lacks explicit response structure or error handling, but sufficient for a batch tool with rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions for each parameter are present. The tool description does not add extra meaning beyond the schema—it repeats the max-10 domain limit and mentions output fields, but that's about return values, not parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Bulk-scan up to 10 domains in parallel. Runs a full security audit on each domain...' and names the return fields (score, NIST-aligned letter grade, finding counts). It also distinguishes from compare_domains, making the tool's scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when you want to audit multiple domains at once' and notes distinctness from compare_domains, a side-by-side analysis. It does not explicitly exclude single-domain scans (e.g., scan_domain), but the guidance is sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the domain-appropriate semantics (shows which CAs are authorized) but does not elaborate on caching behavior or output format, which would be useful given the force_refresh and format parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence states the action and resource, the second clarifies the result's meaning, and the third positions the tool within the scan_domain audit. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only DNS lookup tool with a fully documented schema, annotations, and an output schema, the description is complete. It covers the tool's purpose and context without needing to explain return values or parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of all three parameters with descriptions, so the baseline is 3. The tool description does not add extra parameter semantics beyond mentioning 'domain' in prose, but the schema already handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Look up') and identifies the exact resource ('CAA records for a domain'), clearly distinguishing it from sibling check_* tools that target other DNS record types. The added context about Certificate Authorities further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting it is 'Part of the scan_domain audit,' implying when it fits into a broader workflow. It does not explicitly list exclusions or alternatives, but for a DNS record lookup tool, the record type in the name/description makes the intended usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 safety profile is clear. The description adds behavioral context by explaining the multi-round query process and what it compares (IP answer sets and TTLs), which goes beyond the annotations. It does not mention rate limits or caching behavior, but the force_refresh parameter hints at caching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose and then explaining the method. It is concise and avoids fluff, though the second sentence somewhat repeats the first. No wasted words, but could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, output schema present), the description covers the core behavior and purpose. The output schema exists, so return values are documented elsewhere. The description could mention caching behavior or rate limits, but the annotations and schema cover most needs. It 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about the overall purpose but does not add new meaning to individual parameters beyond what the schema provides. The description mentions 'multiple rounds' which aligns with the 'rounds' parameter, but the schema already explains that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects fast-flux DNS behavior by performing multiple rounds of A/AAAA queries and checking for rapid IP rotation and TTL changes. It explicitly names the resource (domain) and the specific behavior (fast-flux), distinguishing it from sibling DNS check tools like check_mx or check_spf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the method (multiple query rounds, comparing IP sets and TTLs) and the purpose (identifying botnet/malicious infrastructure), which implies when to use it. However, it does not explicitly state when not to use it or mention alternatives, though the sibling list shows many other DNS checks that could be alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds context about the RFC and audit role, but it does not go beyond annotations or reveal additional behaviors such as cache behavior, though schema documents force_refresh. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, direct sentences clearly state what the tool does and where it belongs. Every word earns its place, with no unnecessary technical filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and full schema coverage for parameters, the description only needs to fill the purpose and context gap, and it does. It clearly identifies the subject, standard, and audit context, making the tool adequately complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented by the schema. The description does not add meaning beyond the schema for domain, format, or force_refresh; it only frames the overall purpose of the check rather than enriching parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Validate'), names the exact resource ('HTTPS/SVCB records (RFC 9460)'), and states its purpose ('modern transport capability advertisement'). This clearly distinguishes it from sibling checks like check_dane_https or check_ssl while staying focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by noting it is 'Part of the scan_domain audit,' placing it within a defined workflow. It does not explicitly call out alternatives or when not to use it, but the RFC scoping and audit context provide enough situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safe/read-only nature is established. The description adds useful context beyond annotations: it mentions the use of Team Cymru DNS and the high-risk ASN flagging behavior. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and each sentence adds value—first states the function, second details output and a special feature. No redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a complete schema, annotations, and an output schema, the description is sufficient. It covers purpose, output details, and a unique capability, making it complete for the tool's complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters (domain, format, force_refresh). The description does not elaborate on parameter usage, but since the schema fully documents each parameter, the baseline is 3. It does not add extra meaning, but it also does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core function: 'Map domain IPs to Autonomous System Numbers via Team Cymru DNS.' It also lists specific outputs (ASN, prefix, country, registry, organization) and an added feature (flags high-risk hosting ASNs). This is distinct from all sibling tools, which focus on other DNS/security checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (for ASN lookup) but does not explicitly state when to use it instead of alternatives or mention any exclusion conditions. Given the sibling list, no other tool performs ASN mapping, so the context is somewhat clear, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (it starts an investigation, so mutates state), openWorldHint=true, destructiveHint=false, which align. The description adds async behavior and the 'degrades to info when unprovisioned' condition, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and async nature, second gives degradation condition and points to the status and report tools. Every word is functional; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a start operation, so the description covers async initiation bees. It mentions the follow-up tools for status and report. Given no output schema lowering the burden, and the simple interface (one param), the description is sufficient. Could mention auth or rate limits, but not critical for Ops tool. Slightly below perfect because 'operators-only' behavior is vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description implies the query is the domain, but does not elaborate on format, constraints, or examples. With only one parameter of type string, it's minimal, but the description could have clarified expected input more thoroughly. Since schema provides constraints (min/max length), the description adds little beyond the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an async OSINT investigation for a domain, using a specific verb ('start') and resource. It distinguishes from siblings like the status and report retrieval tools by mentioning polling and retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to poll with osint_investigation_status and retrieve with osint_investigation_report, and notes it is operator-deploy only. Does not explicitly mention alternatives, but the sibling tools make the workflow clear. Missing explicit 'when not to use' but adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral traits: multi-domain, paid, reuses another tool, and ranking criteria. This adds value beyond annotations, though caching or rate limits are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. It front-loads the purpose, follows with key characteristics, and ends with 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the tool ranks leads but does not describe the output format (e.g., list structure, scores). The format parameter hints at verbosity, but the return structure is unclear, leaving a gap for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the input schema already contains detailed descriptions for each parameter. The tool description does not add additional meaning beyond what the schema provides, justifying the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks brand portfolios or domain sets into prioritized CSC sales leads based on product-gap value and severity. It explicitly distinguishes from siblings map_csc_products and batch_scan, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the tool is multi-domain and paid, giving context on when to use. It explicitly names alternatives (map_csc_products, batch_scan) and mentions reuse of map_csc_products, but does not elaborate on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds that it returns risk level, sub-scores, and plain-language summary, and mentions the force_refresh parameter to bypass cache. This provides useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines the core function, second tells when to use. No wasted words. Front-loaded with the key action and output. Highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return value (risk level, sub-scores, summary) despite no output schema. It also explains the force_refresh parameter's purpose. For a composite risk tool, this is sufficiently complete. Could mention caching behavior, but the parameter description covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mentions domain, format, and force_refresh, but the schema already describes all parameters with adequate detail (e.g., 'Auto-detected if omitted'). The description adds no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it computes a composite email spoofability risk score (0-100) combining SPF, DMARC, and DKIM. It distinguishes from sibling tools like check_spf, check_dmarc, check_dkim which are individual checks, by emphasizing it's a composite score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when asked how easy it is to spoof email from a domain, or for a composite email spoofing risk score.' This provides clear context, though it doesn't explicitly state when not to use or mention alternatives. However, the sibling tools list implies the alternative individual checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, destructiveHint: false) already disclose the tool's non-destructive, read-only nature. The description adds behavioral details beyond annotations by specifying that it detects CDN/WAF interception, flags missing or weak protections against XSS/clickjacking/cross-origin attacks, and returns per-header findings. This enriches the agent's understanding 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and packed with specific details (headers, weakness types, CDN/WAF). Every word earns its place; no fluff or redundancy. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key behavior: what headers are checked, what weaknesses are flagged, and what is returned. It also mentions CDN/WAF detection. The presence of an output schema reduces the need to describe return format. It does not mention prerequisites (e.g., HTTPS availability) or edge cases, but for a read-only audit tool with good annotations, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (domain, format, force_refresh) already described in the schema. The tool description does not add any additional parameter-level meaning beyond what the schema provides. It doesn't compensate with extra details, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits a domain's browser-facing HTTP security headers over HTTPS, lists specific headers and what it flags (unsafe-inline/unsafe-eval/wildcards, etc.), and indicates it returns per-header findings. This distinguishes it from sibling tools like check_ssl or check_mx by focusing on security headers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Part of the scan_domain audit', providing context that it's a component of a broader audit. It doesn't explicitly state when to use this tool over alternatives or when not to use it, but the specific scope (HTTP security headers) implies its role. No explicit exclusions are given, but the context is clear enough for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. The description adds valuable behavioral details beyond annotations: compares parent/child NS sets, verifies AA responses, checks glue, and notes the 'infrastructure probe' availability condition. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each packed with relevant information. Front-loaded with purpose, then specifics, then context. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex tool, the description covers the audit goal, the specific checks performed, the conditional probe dependency, and the typical failure modes detected. Output schema exists so return details are covered there. The mention of 'Part of the scan_domain audit' provides integration context. Slight gap: does not explain how results are returned (e.g., structured vs. textual), but output schema compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with meaningful descriptions (domain example, format enum, force_refresh purpose). Description adds no extra parameter semantics beyond schema, which is acceptable given the high coverage. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Audit a domain's nameserver delegation and redundancy' – specific verb and resource, and distinguishes from sibling DNS check tools (e.g., check_mx, check_spf) by focusing on NS delegation, AA responses, and glue. The additional use cases (detect stale delegations, lame nameservers) reinforce purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: 'detect stale registrar delegations, lame nameservers, and intermittent resolution risk.' Mentions it's part of scan_domain audit, giving context. However, it doesn't explicitly state when NOT to use it (e.g., for non-NS checks) or name alternatives, so it's slightly below exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail by revealing exactly what configurations will be flagged (plain NSEC zones, weak NSEC3 params, opt-out flags), going beyond generic labels.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The first sentence states the primary purpose, and the second enumerates the detected conditions, making the tool's scope immediately obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, annotations, and full parameter descriptions, the description is sufficiently complete for this moderately complex check. It could improve by explicitly contrasting with related DNS security checks (e.g., check_dnssec, check_dnssec_chain), but the current content is enough for an agent to evaluate usefulness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter documented (domain, format, force_refresh). The description adds no additional parameter nuance, but it does not need to because the schema already provides clear meaning for all three fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: "Assess zone walkability risk by analyzing NSEC3PARAM configuration." It then names discrete detection targets—plain NSEC zones, weak NSEC3 parameters, and opt-out flags—which differentiates it from broader DNS-related sibling tools like check_dnssec or check_dnskey_strength.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear functional context: this tool is for NSEC/NSEC3 walkability and DNSSEC configuration detail. It does not explicitly name alternatives, but the specificity of the risk target implies when the tool should be used versus general DNS checkers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 operation. The description adds valuable behavioral detail beyond annotations: the tool is operator-deploy only and degrades to info when unprovisioned, explaining a failure mode. This is meaningful additional context without contradicting anything.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary purpose, followed by a differentiation note and deployment context. Every word earns its place—no redundancy or filler. Ideal structure for quickly orienting an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (domain check) with rich annotations, full parameter documentation, and an output schema existing. The description covers key differentiators (realtime, curated, not DNSBL) and failure behavior (degrade to info). It could mention specific use cases or output expectations, but given the simplicity and available structured data, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter already has a clear description (domain, format with enum, force_refresh). The tool description itself doesn't add any extra parameter meaning beyond what's in the schema, so the baseline 3 for high coverage applies. No new information about parameter usage or format is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Check a domain against BlackVeil real-time threat intelligence') with a specific resource (curated intel-gateway feed). It explicitly distinguishes from DNSBL checks, which separates it from siblings like check_dbl and check_rbl, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context by stating it's distinct from DNSBL checks and indicates deployment constraints ('Operator-deploy only; degrades to info when unprovisioned'). While it doesn't explicitly list alternative tools for specific scenarios, the distinction from DNSBL checks gives a clear when-not-to-use signal. More explicit exclusions would elevate it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by clarifying that the tool is owner-gate exempt and uses public cohort data only. It also honestly notes that sector filtering is planned for a future release. This surpasses annotation coverage but does not delve into other behavioral aspects like rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, concise and front-loaded with the core purpose. Every sentence adds value: what it does, what it accepts, what it returns, and access constraints. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately explains the return value ('returns a percentile: scores better than X% of peers'). The tool has 5 parameters, all described in schema, and the description covers usage context with scan_domain. It is complete for a ranking tool with clear annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context such as 'from scan_domain' for the score parameter and notes that sector filtering is planned, but these are minor enhancements. The schema already describes each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('rank', 'accepts', 'returns') and identifies the resource ('domain against its country or global cohort using the GSI benchmark corpus'). It distinguishes from siblings by highlighting the ranking function, which is unique among the listed tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states that the tool accepts a domain score from scan_domain, implying a post-scan use case. It mentions owner-gate exemption for public data. However, it does not explicitly state when not to use this tool or mention alternatives like compare_domains, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds that it returns benchmarks and issues, consistent with annotations. No additional behavioral details beyond the safe, read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines the action, second states usage context. Front-loaded with key purpose. No redundant or vague phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description indicates return of 'security benchmarks and common configuration issues'. Sufficient for a fast, read-only lookup tool. Covers the 3 parameters implicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds context for 'provider' (e.g., 'Google Workspace customers') and hints at what 'profile' and 'format' control. Adds meaning beyond the schema's enum descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns security benchmarks and configuration issues for a specific provider cohort (e.g., Google Workspace). It distinguishes from sibling tools like check_dmarc (per-domain) by focusing on provider-level aggregation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'when asked how an email service provider compares to competitors...' or 'to see typical misconfigurations for a named vendor's customers'. Implicitly excludes individual domain checks, but no explicit alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false (indicating mutating/start) and idempotentHint=false, but description clarifies it starts an async process and returns an investigationId immediately, which is beyond annotations. It also discloses the restricted access (owner/enterprise tier) and the restriction on people-centric OSINT to prevent misuse. This adds valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no redundancy. Front-loads the action and purpose, then adds restrictions and next steps. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Contextual complexity is moderate: async operation, restriction, and follow-up tools are mentioned. No output schema, but description explicitly tells how to get results via other tools, so return value is covered. Minor gap: doesn't specify what happens if query is invalid or requires additional auth beyond tier, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has only one parameter 'query' with min/max length but no description; coverage is 0%, so description must compensate. Description implies 'query' is the email address, but doesn't explicitly state format or validation. However, given only one param, it's fairly inferable. Baseline for 0 params would be 4, but single param with implied type is okay; still, explicit mention would improve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb and resource: 'Start an async OSINT investigation for an email address' with explicit scope ('breach exposure, account correlation'). It distinguishes from siblings by noting the email-specific variant and the async nature, setting it apart from domain, infrastructure, supply chain, and username variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context: mentions it is restricted to owner/enterprise tier, which is a usage condition. It also directs to poll with osint_investigation_status and retrieve with osint_investigation_report, providing next steps. However, it doesn't explicitly state when NOT to use this tool (e.g., for non-email queries) or alternatives beyond the sibling tools, though the sibling context implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate openWorldHint=true and idempotentHint=false, but the description adds crucial behavioral details: the tool is asynchronous and returns an investigationId immediately while the investigation runs in the background. It also discloses access restrictions (owner/enterprise tier). This goes beyond the annotations, though it does not describe edge cases like authorization failures or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each with a clear role: purpose, restriction, and workflow. It is front-loaded with the main action, avoids filler, and every sentence contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple starter tool with one parameter and no output schema, the description adequately covers the full workflow: what it does, the access restriction, and the follow-up steps (poll and retrieve). It does not detail report contents, but that is handled by the report tool. Minor missing details like rate limits or concurrent investigations, but not critical for this async starter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter (query) and 0% schema description coverage, the description must compensate. It clarifies that the query is a username for investigation, which adds meaning beyond the raw schema. However, it does not specify format details (e.g., case sensitivity, whether '@' is needed) or confirm it accepts only one username. It suffices but is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Start' and the resource 'async OSINT investigation for a username', and it specifies the scope (cross-platform presence, breach correlation). This distinguishes it from sibling starters like osint_investigate_email_start or osint_investigate_domain_start by explicitly focusing on username investigations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by stating that this is owner/enterprise tier only and that people-centric OSINT is restricted to prevent misuse. It also explains the async workflow: returns an investigationId immediately, poll with status and retrieve with report. However, it does not explicitly compare to alternative investigation starters (e.g., email, domain), though this is implied by the username focus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, openWorldHint true), the description adds meaningful behavioral details: each run enqueues brand_audit_batch_start, optionally POSTs a webhook on drift, and enforces a per-principal cap of 20 watches. These side effects and constraints are not captured elsewhere. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action, and every sentence adds value: creation, side effects, return value, and constraints. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (recurring scheduling, side effects, webhook, quota), the description covers the key aspects: what it does, what happens on each run, the webhook condition, ownership, and cap. An output schema exists, so return details are covered. Minor missing info like error conditions (e.g., conflict if domain already watched) but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant new semantics beyond the schema: it mentions the webhook behavior (already in schema) and ownership, which is more about tool behavior than parameter specific meaning. No extra value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Creates') and resource ('recurring brand-audit watch') and clearly differentiates from siblings like list_brand_audit_watches and delete_brand_audit_watch. It also mentions the cadence options (daily/weekly/monthly) and side effects, making the tool's function unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly distinguishes this from one-off audits by emphasizing 'recurring' and 'cadence.' It also mentions owner-scoping and a cap of 20 watches, providing constraints. However, it does not explicitly point to alternatives (e.g., brand_audit_single) or state when NOT to use this tool, so a small gap exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing the aggregation of checks and the output (score, grade, maturity, findings). It also discloses the critical nuance about version stamps (scoringModelVersion vs dnsChecksPackageVersion being independent and not comparable) and advises recording scoringConfigHash. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, starting with a clear purpose sentence and then providing usage context and version stamp details. Every sentence adds value, though the version stamp explanation could be condensed. It is efficient for a complex tool with many checks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (aggregates many checks) and lack of an output schema, the description is quite complete: it lists the main checks, explains the output (overall score, NIST grade, maturity, findings), and gives explicit usage guidance plus version stamp handling. It covers the essential context for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema describes all parameters (domain, format, profile, force_refresh). The description does not add significant parameter-specific semantics beyond what the schema provides—it focuses on overall tool behavior. The version stamp explanation is not about parameters. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a full DNS and email security audit for a single domain' with a specific verb and resource. It distinguishes itself from sibling check_* tools (e.g., check_spf) by emphasizing 'full audit' and aggregation, and from batch_scan by explicitly saying 'single domain'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases: 'Use for a comprehensive single-domain audit, to get a domain's overall security grade, or to assess email security maturity.' This gives clear context on when to invoke it, though it does not explicitly state when not to use it or name alternative tools (like individual checks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable context about the fix confirmation workflow and purpose, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. First sentence states purpose clearly, second provides usage guidance. Front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, rich annotations, many siblings), the description covers the essential usage context. No output schema exists, but description doesn't need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full parameter descriptions (100% coverage). Description does not add additional meaning beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 're-check' and resource 'security control after applying a fix', clearly distinguishing it from sibling check_* tools which are for initial inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after fix applied, to verify remediation) and when not to (not for initial inspection). Doesn't name alternatives but implies check_* tools for initial inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint=true and destructiveHint=false. The description adds genuine value by disclosing the owner-scoping edge case ('auditIds owned by other principals surface as notFound') and previewing the return shape (audit status, 'N/M' progress, per-target statuses). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly-written sentences with every clause earning its place. The first sentence front-loads the verb and purpose; the second packs return-shape details and a critical scoping edge case into a single clause. Zero fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter polling tool with an output schema, the description covers all key aspects: purpose, async lifecycle, return shape, and the ownership-related notFound edge case. Given the available schema context and annotations, there are no material gaps that would prevent an agent from using this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description stays at the schema's 100% coverage level. The auditId parameter is fully documented in the schema ('Audit ID returned by brand_audit_batch_start'), with the description adding only the word 'enqueued' as extra context. Schema does the heavy lifting, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening verb-noun pair 'Poll the status of an enqueued brand audit' precisely defines the operation with a specific verb (poll) and resource. It clearly distinguishes itself from sibling tools like brand_audit_single, brand_audit_batch_start, and brand_audit_get_report, making the tool's role in the async workflow unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context: 'Poll the status of an enqueued brand audit' implies usage after brand_audit_batch_start initiates work, and the 'queued | running | completed | failed' state machine signals when it applies. However, it doesn't explicitly name alternatives or state when NOT to use it (e.g., vs. brand_audit_get_report).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description explains what is actually validated, the limitation that the certificate type is not determined from the bare a= tag, the DMARC enforcement prerequisite, and that findings cover missing/malformed records or unmet prerequisites. This adds meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, starts with the core action and target, and every clause adds value: validation logic, limitation, prerequisite, returned findings, and use case. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations describe safety, the schema fully documents parameters, and an output schema exists, the description provides sufficient behavioral detail: exact record, fields validated, limitation, prerequisite, and outcome types. Nothing critical is missing 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents domain, format, and force_refresh. The description adds domain semantics by specifying the lookup at default._bimi.<domain>, but it does not add further detail on format or force_refresh beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (default._bimi.<domain>), a precise action (check/validate), and the exact fields validated (l= and a=), while also verifying the DMARC prerequisite. This clearly distinguishes it from the many other DNS/record checking siblings like check_dmarc or check_tlsrpt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it 'to assess brand-indicator readiness in inboxes' and notes it is 'part of the scan_domain audit,' providing clear context. It does not name alternatives or state when not to use it, but the use case is unambiguous enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds valuable context by explaining the DNS lookup mechanism and that it is part of a larger audit, which meaningfully supplements 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, each adding unique value: what the tool does, how it works, and how it differs from a sibling. No filler or redundant restatement of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations are present, the description provides the necessary behavioral context: the DNS record type, port, domain pattern, distinction from SMTP DANE, and audit context. This is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. The description adds context for the domain parameter by showing how it is used in the TLSA lookup pattern (_443._tcp.{domain}), but format and force_refresh are not addressed in the description. This is adequate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Verify') with a clear resource ('DANE certificate pinning for HTTPS connections') and includes the exact check mechanism (TLSA records at _443._tcp.{domain}). It explicitly distinguishes itself from the sibling tool check_dane, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool (HTTPS/port 443) and explicitly differentiates it from check_dane for SMTP/port 25. It also places it within a scan_domain audit. It does not enumerate broader exclusion criteria, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds behavioral context by explaining it probes multiple selectors, validates algorithm strength, and reports key strength, which goes beyond annotation details and helps the agent anticipate multiple DNS queries and analysis. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding distinct value: what it does, what it validates, and when to use it. It is front-loaded with the primary verb and object, contains no fluff or redundant phrasing, and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully documents parameters and an output schema exists, the description does not need to explain return values. It covers purpose, usage context, and behavioral details (selector probing, algorithm validation, key strength reporting), which is more than sufficient for a read-only DNS checking tool. The description is complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% parameter description coverage, so the baseline is 3. The description adds slight meaning about selector behavior ('Probes common selectors') which connects to the optional selector parameter, but it does not elaborate on format or force_refresh beyond what the schema already states. The added value is minimal but not redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up DKIM records for a domain, probes common selectors, validates signing algorithms (RSA-1024/2048, Ed25519), and reports key strength. This distinct purpose differentiates it from sibling tools like check_spf, check_dmarc, and check_mx, and the verb 'look up' combined with the resource 'DKIM records' is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 verify that outbound email signatures are cryptographically sound.' It also notes it is part of the scan_domain audit, giving context for when it might be invoked. However, it does not explicitly state when not to use it or name alternative tools, though the purpose naturally excludes other DNS record checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. Description adds specific details about DNSKEY/DS validation and reporting, which goes beyond the basic safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. Clearly structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description fully explains the tool's function and context. Output schema exists, so return values are not required in the description. No missing essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions, and the tool description does not add additional semantic meaning beyond what schema already provides. Coverage is 100%, so baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it checks DNSSEC status, verifies tamper-proofness, and validates DNSKEY/DS records. Distinguishes from sibling tools by focusing on DNSSEC status and mentions being part of the scan_domain audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context as part of scan_domain audit but does not explicitly contrast with alternatives like check_dnssec_chain. However, purpose is clear enough for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only, idempotent, open-world, and not destructive, so there is no contradiction. The description adds useful non-obvious behavior beyond those annotations, such as flagging syntax errors and enumerating the 'trust surface'. It stops short of describing cache semantics in prose, but the schema already covers force_refresh.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the first sentence giving the action and resource and the following sentences adding only high-value context: what it returns, whether it detects errors, and when to choose it. There is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, clear annotations, and only three parameters, the description fully supports selection and invocation. It covers purpose, result semantics, syntax validation, and workflow context. The expected response format does not need to be in prose because an output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents domain, format, and force_refresh, including defaults and intended use. The description adds no parameter-specific information beyond the output-level concept of validation, which matches the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action and resource: 'Look up and validate the SPF record for a domain.' It then clarifies what the tool provides beyond the name—listing authorized IPs, flagging syntax errors, and showing the trust surface—making it easy to distinguish from siblings like check_mx, check_dmarc, and check_dkim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage trigger: 'Use when you need to know who is permitted to send email as a domain.' It also situates the tool within the broader scan_domain audit, providing enough context for selection, though it does not explicitly call out alternatives or when-not-to-use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: parallel probing, ~16 common prefixes, and flagging of insecure advertisements such as plaintext IMAP/POP3 without encrypted variants. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, then output, then usage guidance. Every sentence earns its place with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the strong annotations, full schema coverage, and presence of an output schema, the description is complete enough. It explains what the tool does, what it returns, and when to use it, without needing to repeat structured field details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents domain, format, and force_refresh. The description adds general context about SRV probing but does not add parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool maps a domain's DNS-visible service footprint by probing ~16 common SRV record prefixes, which is a specific verb+resource+method. It distinguishes itself from sibling DNS tools like check_mx or check_spf by focusing on SRV records and insecure service advertisements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when asked to map DNS-visible services or flag insecure service advertisements,' giving clear context for when to invoke it. It does not explicitly mention when not to use it or name alternative tools, but the usage guidance is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive behavior. The description adds specific behavioral details: the DNS query, validation of rua= and https: destinations, flagging missing/duplicate/invalid records. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that are information-dense with no fluff. Front-loaded with purpose, then method, then context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers purpose, DNS query, validation logic, and its role in the audit. An output schema exists, so return values need no explanation. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage). The description adds context about the domain used in the DNS query but doesn't elaborate on format or force_refresh, which are already well-documented in the schema. Meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks for SMTP TLS Reporting (TLS-RPT) configuration, queries the specific DNS record, and validates the reporting destination. It distinguishes itself from sibling DNS-check tools by focusing on a specific record type and mentions its complementary role to MTA-STS.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it complements MTA-STS and is part of the scan_domain audit, implying when to use it. It does not explicitly list when not to use it or name alternative tools, but the implication is strong enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds that the tool is async, returns immediately with { auditId, queuedAt, etaSeconds }, and requires polling. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence explains the tool's identity and async nature, the second covers return value and subsequent steps. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of an async workflow with sibling tools for status and findings. The description explains the flow and return format. No output schema, but the return structure is explicitly given. Complete for its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description says 'Same args as discover_brand_domains' but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an async brand-domain discovery for an exact seed domain, distinguishing it from the synchronous sibling 'discover_brand_domains' which can time out. The verb 'start' and resource 'brand-domain discovery' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this async version (when the sync version might time out) and directs the user to poll with 'discover_brand_domains_status' and fetch results with 'discover_brand_domains_findings'. It does not explicitly state when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds owner-scoping and specific status values, which provides useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and contains no extraneous information. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, no output schema, and clear annotations, the description covers everything needed: purpose, return types, and scoping rules. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a detailed description for operationId. The description mentions it's from discover_brand_domains_start, which adds minimal context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it polls the status of an async brand-domain discovery started by discover_brand_domains_start. It specifies the return values (status and progress) and distinguishes itself from the start tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the tool is used for polling after starting discovery and notes that operationIds owned by others return notFound. It provides clear context for when to use, though it could explicitly state not to use for initiating discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by detailing that it correlates SPF, NS, TXT, SRV, and CAA records to reveal third-party vendors, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both front-loaded with purpose. No fluff; every sentence adds value. The description is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the agent must infer return format. The description gives a good overview but does not detail output structure. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters documented. The description does not add significant new meaning beyond the schema, but it does provide overall context. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Map') and resource ('DNS-visible third-party service dependencies for a domain'). It also distinguishes from siblings by explicitly noting it is not for listing who can send email (use check_spf).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use when asked to map third-party or supply-chain dependencies — not for listing who can send email (use check_spf for that).' Clearly states when to use and when not to use with an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds extra detail not in annotations, such as the 'degrades to info when unprovisioned' behavior and that it returns progress metadata. This goes beyond the basic annotations and provides useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no unnecessary elaboration. It efficiently communicates the core action, key input, and expected output, adhering to the principle of minimal but sufficient information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-polling tool with a single parameter and no output schema, the description is complete. It specifies the input, the action, the return values (status and progress metadata), and even an edge case ('degrades to info'). No critical behavior is omitted for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully specifies the only parameter (investigationId) with type and length constraints, achieving 100% schema coverage. The description merely restates 'by investigationId' without adding semantic meaning (e.g., where the ID comes from or its format). Thus, it adds little beyond the schema, warranting a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Poll the status of an OSINT investigation by investigationId.' It uses a specific verb ('poll'), names the resource ('status of an OSINT investigation'), and identifies the key identifier. It also distinguishes from sibling tools like osint_investigate_domain_start by focusing on status retrieval rather than initiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage constraints (e.g., 'Operator-deploy only') and hints at behavior ('degrades to info when unprovisioned'). However, it does not explicitly state when to use this tool relative to starting an investigation or polling other resources, though the 'investigationId' parameter implies it should be used after a start operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With minimal annotations (openWorldHint:true, readOnlyHint:false), the description carries the burden of behavior disclosure. It effectively communicates the async nature, immediate return of scanId, the degradation behavior ('degrades to info when unprovisioned'), and the poll/retrieve workflow. This adds substantial non-obvious context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, constraint, and next steps. No fluff or repetition. Highly scannable and information-dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async start operation with two parameters and no output schema, the description covers the essential flow (start, poll, retrieve) and the degradation behavior. It misses details on parameter validation or error cases, but given the tool's moderate complexity, it is nearly complete. A small gap exists around the 'providers' parameter, but overall it is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that 'target' is a domain, which helps, but it says nothing about 'providers', its format, or possible values. With two parameters and no schema descriptions, this is a gap—leaving the agent underinformed about half the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start an async cloud-bucket discovery scan for a target domain' with a specific verb ('start'), resource ('cloud-bucket discovery scan'), and target ('domain'). It is distinct from sibling tools like scan_buckets_status and scan_buckets_findings, which are explicitly referenced as follow-ups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is async, returns a scanId immediately, and instructs the user to poll with scan_buckets_status and retrieve with scan_buckets_findings. The 'Operator-deploy only' caveat gives deployment context. However, it doesn't explicitly discuss when to use this tool versus alternatives or mention any exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds valuable behavioral nuance: 'degrades to info when unprovisioned' and specifies return contents (status and progress metadata), which goes beyond the annotations. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every phrase contributes meaning. It avoids redundancy, making it highly concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple polling tool with one parameter, annotations covering safety, and no output schema, the description is sufficient. It mentions the return values (status and progress metadata) and the degradation behavior, which covers all necessary information for an agent to use it correctly. No missing critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, scanId, and the schema provides no description (coverage 0%). The description uses 'by scanId' but does not elaborate on its format or origin beyond the name. Since it is a single obvious identifier, the description provides minimal added meaning, but given the low schema coverage, it partially compensates by implying the identifier is from a scan start operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls the status of a cloud-bucket discovery scan by scanId, using a specific verb and resource. It is distinct from sibling tools like scan_buckets_start (starts a scan) and scan_buckets_findings (retrieves results), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: after starting a scan, poll its status via scanId. It does not explicitly name alternatives or when-not-to-use, but the phrasing 'Poll the status' and the context of sibling tools make the intended use clear. The 'Operator-deploy only; degrades to info when unprovisioned' adds conditional context, though not explicit comparisons to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-idempotent. The description adds meaningful behavior beyond annotations: it is async, returns an immediate ack object, consumes quota per domain, and supports optional caller-supplied candidates. Minor gap: no auth/enterprise tier details are mentioned, though the schema mentions enterprise tier for the view parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary action, and structured into three logically ordered sentences: what it does, what is returned and next steps, and the budget implication. No repetitive or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters with full schema coverage, an output schema, and sibling tools, the description covers the critical missing context: async behavior, quota cost, batch size limit, and follow-up tool names. It does not explicitly mention the auth requirements or `ownership_verified` conditions, but these are partially captured by the schema and the complexity is moderate, so a 4 is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters including defaults, enums, and constraints. The description adds no per-parameter meaning beyond the schema, but it reinforces the overall batch and quota semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Enqueue an async brand audit across up to 50 target domains' and enumerates the key options (discovery depth, brand aliases, candidate domains). It also clearly distinguishes from sibling tools by naming brand_audit_status and brand_audit_get_report for follow-up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the async workflow: returns immediately, poll with brand_audit_status, fetch results with brand_audit_get_report. This removes ambiguity about when to use this tool vs its sibling tools. Also implies it is the batch entry point versus brand_audit_single.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful operational behavior: it performs discovery and lookups, classifies results, and is gated by tier-specific monthly quotas. This provides useful rate-limit and authorization context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, then adds the discovery/classification workflow and quota gating. Every sentence carries useful, non-redundant information; the minor typo 'shadowIt' does not undermine clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with full schema coverage and an output schema, the description provides a strong high-level account of the audit, outputs, and quota constraints. It does not elaborate on all modes (view, discovery_mode, planner_mode, ownership_verified), but those are fully documented in the schema and are secondary to the core purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter with enums, defaults, and constraints. The description only highlights depth, brand_aliases, and candidate_domains, but those are also described in the schema; it adds no new semantic meaning beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Run a full brand audit on a single target.' It then details the concrete outputs (domain discovery, registrar/registrant lookups, classification into named relationship categories), clearly differentiating this tool from batch/status siblings by the explicit 'single target' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the single-target audit context and lists optional kinds of inputs (depth, aliases, candidate domains), but it never explicitly says when not to use it or points to an alternative like brand_audit_batch_start. The sibling names partially imply the choice, but the description itself provides no exclusion or comparison guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately reflects the tool's read-only, idempotent nature by using terms like 'audit' and 'reports.' It adds context about being independent of chain validation, but does not elaborate on potential side effects or limitations beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences to convey purpose, output, independence, and usage. It avoids redundancy and each sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, usage, and key behavior, and mentions its position in the scan_domain audit. It does not describe output format or error conditions, but these are not critical for a simple read-only tool with clear schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full coverage with clear descriptions for each parameter (domain, format, force_refresh). The tool description adds no additional information about these parameters, so it contributes nothing beyond the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: auditing the cryptographic strength of DNSKEY signing algorithms, reporting the algorithm used, and flagging deprecated ones. It also explicitly distinguishes this from DNSSEC chain validation, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'Use when asked what algorithm is used for DNSKEY signing keys, or if deprecated DNSKEY algorithms are in use.' It also notes the tool is part of a broader audit, giving context on when it might be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, and harmless, which cover the safety profile. The description adds that it detects 'active' domains, implying a live scan or freshness aspect, and mentions the type of registrations (by attackers). It does not detail output structure, but with annotations covering safety and the description adding scope, this is strong; minus one for not describing the return format or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise two-sentence block: first sentence defines the tool's function and use case, second sentence differentiates from key siblings. No filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a clear, narrow scope with a detailed input schema and an output schema (not shown but noted). The description covers the purpose, use context, and differentiation from two key siblings. It could mention what the output looks like (e.g., list of domains) but the output schema likely covers that, and the description is sufficient for a straightforward scan tool with rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are well-described in the schema. The description adds a semantic focus on impersonation and 'active' domains, which reinforces the domain parameter's purpose, but does not add new syntax or format details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects active typosquat and lookalike/homoglyph domains that impersonate a brand, with specific examples of character-substitution and visual-confusion. It explicitly distinguishes from siblings check_shadow_domains and discover_brand_domains, meeting the high bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use context: for detecting impersonation domains used in phishing. It names two specific sibling tools and how they differ, giving clear guidance on when not to use this tool (e.g., for TLD variants with auth gaps or legitimate portfolio discovery).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 context about what is checked (RBLs and reverse DNS) and notes the distinction from check_rbl. With annotations present, this is more than sufficient, though it doesn't describe output format or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, both informative and front-loaded. The first sentence states the core purpose, the second adds usage guidance and sibling differentiation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool is read-only with idempotent hints, the description covers the essential context: purpose, usage, and differentiation. It doesn't mention potential caveats like cache behavior (though force_refresh is in the schema), but for a simple read-only check, this is adequate and slightly above minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and all parameters (domain, format, force_refresh) are already well-described in the schema. The description adds no additional meaning beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks MX IP addresses against spam blocklists (Spamhaus, Barracuda, SORBS) and verifies reverse DNS. It explicitly distinguishes from check_rbl, which checks a specific IP directly, providing clear differentiation from a closely related sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Use when you want to know if your mail server IP is blacklisted, or if your MX is on any blocklist') and names an alternative tool (check_rbl) with a clear distinction. This fully satisfies the criteria for usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description doesn't need to repeat them. It adds that the tool flags weak/missing email auth for spoofing, which is useful context. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action and immediately followed by usage guidance. Zero wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and good annotations, the description covers the core purpose and distinction from sibling tools. It doesn't explain return values (output schema handles that) or edge cases, but for a check tool this is sufficiently complete. Could mention limits like scope of TLDs, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes all three parameters (domain, format, force_refresh). The description doesn't add parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find'), resource ('alternate TLD variants of a domain'), and purpose (weak/missing email auth for spoofing), and explicitly distinguishes from check_lookalikes, 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance: 'Use when asked about TLD variants with email auth gaps' and contrasts with check_lookalikes, which is a concrete alternative. This tells the agent exactly when to use and when to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so no side effects. The description adds context that the baseline is a policy object, not a prior scan, and clarifies drift tracking should use analyze_drift. It does not contradict annotations. However, it could further detail caching behavior or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence states the core purpose, second sentence provides usage guidelines and alternatives. Highly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 params, nested object, no output schema), the description covers the essential purpose and usage context. It lacks information about output format or what the compliance result looks like, but remains sufficient for an agent to determine when to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so baseline is 3. The tool description mentions 'fixed policy baseline' but does not add additional parameter-level guidance beyond the schema. The nested 'baseline' object is well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares a domain's current security configuration against a fixed policy baseline to determine compliance. It uses specific verbs ('compare') and resources, and explicitly distinguishes from siblings like analyze_drift and compare_domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('check whether a domain meets a policy requirement') and when not to use it ('not for tracking improvement/regression over time' or 'comparing multiple domains'), directing to alternatives (analyze_drift, compare_domains).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), description adds async polling behavior and owner-scoped access, which are useful behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff, front-loaded with purpose, clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers async nature, return states, and owner scoping; lacking explicit polling guidance but adequate given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3; description adds value by linking operationId to the start tool, clarifying its origin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool fetches ranked candidate domains for an async run started by discover_brand_domains_start, distinguishing it from sibling tools like the start and status tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use after discover_brand_domains_start and describes return states (notReady when in-flight, result when complete), but does not explicitly mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds significant behavioral context beyond annotations: sample nature, lower bound count, missing hosts without public certificates, per-source coverage field. No contradiction with readOnlyHint/idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, immediate limitation details. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a read-only, idempotent tool with no output schema. Could add result shape or pagination, but not required given the behavioral clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all three parameters with descriptions (100% coverage). Description adds context about output nature but does not enhance parameter-level semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Find subdomains' with specific resource 'domain using Certificate Transparency logs'. Distinct from sibling tools focused on DNS checks or brand audits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit context for discovery of shadow IT and forgotten services. Clearly states limitations (sample vs inventory) but does not explicitly compare to alternative subdomain tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining what the output contains (percentile, mean, common failures) and implies safe, read-only behavior. No contradictions or missing safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first explains the tool's function, second gives usage guidance. No wasted words, front-loaded with key action. Ideal length for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full schema coverage, good annotations, and no output schema, the description adequately explains the tool's purpose and output concept. Could benefit from a brief mention of how the percentile is computed or the time range, but overall complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear enum descriptions and defaults. The description adds no new information about the parameters beyond what is in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('industry benchmark data') and the context (domain's security score relative to sector/country). It lists concrete outputs (percentile, mean score, common failures), distinguishing it from sibling check tools that focus on individual tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when asked how a score compares to the industry average, what percentile a score is in, or what the most common security failures are in an industry or sector.' This covers the main use cases without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive, so the base requirement is met. The description adds valuable behavioral details beyond annotations: 'notReady' polling semantics, 'pdfUrl' being an authenticated download link requiring the same bearer credential, and 'pdfPending' for rendering state. This is meaningful supplementary information that helps the agent handle edge cases correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each earning its place. The first establishes the core function, the second covers parameter behavior, and the third handles edge cases (notReady, pdfUrl, pdfPending). No filler, front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists Rodríguez, the description appropriately covers runtime behaviors not in the schema: polling (notReady), authentication for pdfUrl, rendering status (pdfPending). This is complete for a tool with two parameters and a rich output contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are 100% documented in the schema, so baseline is 3. The description enhances this by clarifying the semantic distinction: `target` yields per-target CheckResult, while omitting it yields audit-level aggregate. It also explains the meaning of the returned statuses (notReady, pdfUrl, pdfPending), adding value beyond the schema's bare field definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Fetch the result JSON for a brand audit.' It clearly distinguishes this tool from siblings (e.g., brand_audit_status, brand_audit_batch_start) by focusing on retrieving results. The dual mode (per-target vs. aggregate) is explicit, removing ambiguity about what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use it (for completed audits) and explains the behavior of the optional `target` parameter eagerly. It implicitly signals not to use it for in-flight audits by mentioning 'notReady' polling. However, it does not explicitly name alternative tools (e.g., brand_audit_status) for checking status, so a bit more exclusivity would push it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, lowering the bar. The description adds meaningful behavioral context by detailing the MX resolution and TLSA lookup at _25._tcp.<mx-host>, and the DNSSEC-backed verification purpose. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (four sentences) and front-loaded with the core purpose. Every sentence adds value: functionality, mechanism, usage trigger, alternative tool, and audit context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema and annotations, the description covers all necessary aspects: the exact DNS lookup procedure, the security rationale, when to use it, and how it differs from the HTTPS variant. It is complete for a DNS-checking tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context about the domain parameter (MX hosts, port 25) but does not provide additional syntax or meaning for 'format' or 'force_refresh' beyond what the schema already explains. It is adequate but not enriching.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Check') and resource ('DANE/TLSA certificate pinning for SMTP at port 25'), and distinguishes from the sibling tool check_dane_https by explicitly mentioning port 25 and HTTPS port 443. This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use when asked if SMTP connections are protected by DANE/TLSA pinning' and 'For HTTPS DANE at port 443, use check_dane_https instead.' Also notes it is 'Part of the scan_domain audit,' giving clear context for when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by detailing what the tool shows (enforcement level, alignment mode, reporting destinations), but does not disclose potential error modes or network behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, outputs, and usage/alternatives. Every sentence contributes new information, and it is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has robust annotations, full schema coverage, an output schema, and clear sibling context. The description covers purpose, usage, and differentiation, making it 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter has a clear description (domain, format, force_refresh). The description does not add extra meaning beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Look up and validate the DMARC record'), clearly states the domain scope, and explicitly distinguishes itself from sibling tools like check_shadow_domains and assess_spoofability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 to determine a domain's DMARC enforcement level, whether it sends aggregate reports, or if it is protected against email impersonation') and names alternatives with their focus, providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and idempotentHint=true, and description augments with concrete behavior: queries `_mta-sts.<domain>`, fetches policy file, reports mode and MX coverage. Says 'only' for current policy fetch, transparent about scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences are well-structured, opening with the purpose, then mechanics, then usage guidance and sibling distinction. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only DNS check with schema coverage and annotations, the description fully covers what is checked, why, how to contrast with related tools, and context within scan_domain audit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all three parameters at 100% coverage. Description does not add substantial parameter-level meaning beyond what schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it checks MTA-STS for inbound SMTP TLS enforcement, specific verb 'check' with resource (_mta-sts DNS record and policy file), and distinct from check_dane. It reports mode and MX coverage, so highly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use case: 'Use to verify whether inbound SMTP is protected against TLS downgrade or MITM' and calls out the alternative check_dane using TLSA pinning, clearly distinguishing when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses a crucial behavioral nuance: certificate data comes from public Certificate Transparency logs and may differ from the currently served certificate. It also explicitly states what is NOT returned (negotiated TLS versions/cipher suites), preventing agent misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, and every sentence contributes value. It combines scope, output expectations, a key pitfall, limitation disclosure, and usage guidance with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and the annotations cover safety, the description still provides a complete operational picture: what is checked, where data comes from, a meaningful caveat, and explicit limitations. The agent can both select and invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters already have meaningful descriptions, including the enum for format and force_refresh behavior. The description adds high-level context but does not need to repeat parameter syntax, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Check the HTTPS/TLS posture of a domain' with concrete sub-checks like HTTPS reachability, HSTS policy, redirects, and certificate metadata. This distinguishes it from sibling DNS/security checks and makes immediate sense to an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use to verify HTTPS/HSTS configuration and certificate issuer/expiry' and notes it is 'Part of the scan_domain audit.' It lacks explicit exclusion or alternative-tool guidance, but the stated use cases are clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds concrete scope detail ('16 provider families' and lists them) and warns that discover_subdomains returns only a CT sample, not a full inventory. This is additive context, though it doesn't disclose the default 15-name built-in sweep (which is documented in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: the first states the core purpose, the second lists coverage, the third gives usage and pairing guidance. No filler or redundant repetition; each sentence contributes meaningfully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, output schema, and annotations, the description covers the key facts an agent needs: what the tool does, when to invoke it, and a caveat about widening the candidate set. The default 15-name sweep is documented under the subdomains parameter, so it need not be repeated. The description is complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the input schema (100% coverage). The description itself does not add parameter-level semantics beyond the schema—its extra notes about provider families and pairing are about output scope and workflow, not parameter meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Sweep subdomains for dangling CNAMEs pointing to deprovisioned cloud services that could be claimed by an attacker,' clearly stating the verb, resource, and vulnerability. It lists provider families, distinguishing it from sibling DNS checks like check_mx or check_spf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when asked if subdomains are pointing to deprovisioned cloud services' and gives a complementary action with 'Pair with discover_subdomains to widen the candidate set.' This provides clear when-to-use context and an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds value by stating it shows 'relative scores, category gaps, and unique weaknesses' and that format is 'Auto-detected if omitted'. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains what the tool returns (relative scores, gaps, weaknesses) and domain count constraints. Feels complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning by specifying '2–5 domains' and 'Auto-detected if omitted' for format, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool does a 'Side-by-side security comparison of 2–5 domains', with specific verb 'compare' and resource 'domains'. It distinguishes from siblings like 'compare_baseline' by focusing on multiple domains and relative scoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when comparing your security posture against a competitor, or doing a head-to-head comparison between multiple domains.' It provides clear context, though it does not list when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by listing return fields and specifying owner-scoping, which is not in annotations. It does not contradict annotations and provides context beyond what structured metadata conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and includes only essential details like the return fields and scoping. Every word earns its place, no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, output schema exists), the description provides all needed context: what it returns, the fields included, and that it's owner-scoped and read-only. It is complete for an agent to correctly invoke and interpret results without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the schema covers 100% of parameters trivially. Description doesn't need to explain parameters, and the baseline for 0 params is 4. No additional parameter semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Returns the caller's recurring brand-audit watches' with specific fields (watchId, domain, interval, etc.), making its purpose unambiguous. It distinguishes itself from sibling tools like register_brand_audit_watch and delete_brand_audit_watch by indicating it only lists existing watches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Owner-scoped' and 'Read-only', implying it is for viewing one's own watches and safe to call anytime. While it doesn't explicitly name alternatives, the context of sibling tools like register/delete makes usage clear. It conveys when to use this tool versus others without explicit exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses additional behavior beyond annotations: async nature (returns investigationId immediately), polling requirement, and degradation to 'info' when unprovisioned. This adds transparency without contradicting the provided annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with no unnecessary words. It conveys the core purpose, async behavior, and a key caveat in two sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential aspects: what it does, how to use it (poll for status), and a deployment caveat. It does not detail return structure, but since no output schema is provided and the tool is simple, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'query' parameter as accepting domain, IP, or org, which is not evident from the schema alone (simple string with length constraints). This significantly enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an async deep-infrastructure OSINT investigation for domain, IP, or org queries, effectively distinguishing it from sibling tools like osint_investigate_domain_start and osint_investigate_username_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides guidance on when to use (async, for domain/IP/org) and mentions polling with osint_investigation_status, though it does not explicitly contrast with all alternatives. The 'Operator-deploy only' note adds deployment context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds useful context about what data is returned and that RDAP is a 'modern WHOIS replacement,' which goes beyond the structured 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with zero filler. The first sentence states the action and primary outputs; the second gives use cases and sibling differentiation. Information is front-loaded and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, full schema coverage, and presence of an output schema, the description provides sufficient context: what the tool does, what it returns, when to use it, and how it differs from check_ns. No critical operational gaps remain for a read-only lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: domain, format, and force_refresh are all individually documented in the schema. The description adds no additional parameter-level detail beyond what the schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Fetch domain registration data via RDAP' and enumerates concrete outputs (registrar, registrant contact, dates, EPP codes, domain age). It also distinguishes itself from check_ns, making the tool's purpose unambiguous among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: 'when asked who registered the domain, who the registrar is, or when the registration expires.' It also names the alternative check_ns and clarifies the difference, giving the agent clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the drift classification, score delta, and lists of improvements/regressions, which is useful beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose and output, and includes the usage directive. Every sentence adds distinct value with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage, detailed param descriptions, and clear annotations, the description is complete for a 4-param tool with no output schema. It explains both the output format and parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description's main text adds significant clarity for the 'baseline' parameter, distinguishing it from a policy object and directing to compare_baseline. Other parameters are well-described in the schema, so the description provides value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('measure'), identifies the resource ('domain's DNS security posture'), and clearly distinguishes the tool from its sibling 'compare_baseline' by contrasting improvement over time vs. compliance against a fixed policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('did our security score improve or regress since last time?') and when not to ('distinct from compare_baseline which checks compliance against a fixed policy'), naming the alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (read-only, idempotent), the description adds behavioral details: 'degrades to info when unprovisioned' and 'reads can be owner-scoped'. This gives extra context about failure modes and scoping, though it does not enumerate all edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three short sentences to convey purpose, constraints, and parameter roles. No redundant or verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool, it provides sufficient context: when to use, permission hints, and parameter details. Output is not described, but that is acceptable given the tool type and absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (scanId, target, providers) are explicitly described: scanId is required for owner-scoped access, and target/providers are optional filters. This provides full semantic coverage for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving findings from a completed cloud-bucket discovery scan. It is distinct from sibling tools like scan_buckets_start and scan_buckets_status, and the name reinforces purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It indicates when to use (after a completed scan) and notes optional filters, but does not explicitly contrast with alternatives (e.g., 'use instead of scan_buckets_status'). The mention of 'Operator-deploy only' provides some deployment guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds permanent deletion semantics, ownership scoping, the notFound response for other principals, and confirmation of deletion. This gives the agent a full picture of side effects and error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and every clause adds value—permanence, owner scoping, notFound behavior, and deletion confirmation. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with strong annotations and an output schema, the description covers the essential action, the permission/ownership model, the error case, and the return value. It is self-sufficient in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description ('Watch ID returned by register_brand_audit_watch') is already helpful. The tool description additionally clarifies that the watchId must be owned by the caller, adding an ownership constraint that is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Permanently removes a recurring brand-audit watch by watchId,' which is a specific verb (removes) and resource (recurring brand-audit watch). It clearly distinguishes from sibling tools like register_brand_audit_watch and list_brand_audit_watches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when this tool applies (deleting a watch owned by the caller) and includes the owner-scoped caveat with notFound behavior. It doesn't explicitly mention alternatives or exclusions, but the purpose is so distinct that usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![bv-mcp MCP server](https://glama.ai/mcp/servers/MadaBurns/bv-mcp/badges/card.svg)](https://glama.ai/mcp/servers/MadaBurns/bv-mcp)

Score Badge

Copy to your README.md:

[![bv-mcp MCP server](https://glama.ai/mcp/servers/MadaBurns/bv-mcp/badges/score.svg)](https://glama.ai/mcp/servers/MadaBurns/bv-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MadaBurns/bv-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server