DMARKOFF — DMARC, SPF & DKIM Analytics

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

Annotations already provide readOnlyHint and idempotentHint. The description adds that it is a live real-time lookup, returns errors and warnings, and does not require a project. This fully discloses the tool's behavior without contradiction.

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

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

Three concise sentences: first states function, second clarifies scope, third lists use cases. 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.

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

With 2 simple parameters, clear annotations, and no output schema, the description covers purpose, usage scope, and behavior completely. An agent has sufficient information to decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, providing baseline semantics. The description adds value by showing the DNS record pattern (<selector>._domainkey.<domain>) and provides examples for domain and selector, enhancing understanding beyond the schema.

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

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

The description clearly states it performs a live DKIM DNS lookup, queries the <selector>._domainkey.<domain> TXT record, and returns the DKIM key record, errors, and warnings. It distinguishes itself from sibling tools like dns_check_dmarc and dns_check_spf.

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

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

The description explicitly says it does not require a project and works for any domain, even unmonitored ones. It provides use cases: verify DKIM selector existence, check key length, diagnose signing failures. No explicit alternatives are listed, but the context is clear.

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

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

Annotations already declare readOnly and idempotent hints. Description adds value by explaining it performs a real-time query and returns parsed policy, errors, warnings, which is beyond the 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.

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

Three concise sentences front-loaded with the core action and output. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains what it does, what it returns, and when to use it. Could mention it returns a parsed object, but still sufficient.

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

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

Schema covers the single parameter with description. The tool description adds usage context (works for any domain) but doesn't add new semantic details beyond the schema. Baseline score of 3 is appropriate given 100% schema coverage.

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

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

Description explicitly states it performs a live DMARC DNS lookup, queries a specific TXT record, and returns parsed policy, errors, and warnings. This clearly distinguishes it from sibling tools like dns_check_dkim and dns_check_spf.

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

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

Provides explicit use cases: verify DMARC policy, check syntax errors, confirm DNS updates. Notes it works for any domain without needing a project. Lacks explicit when-not-to-use but context is clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds crucial behavior: it queries DNS in real time, and lists the return format (SPF record, DNS-lookup count, parsed include tree, TXT diagnostics, errors, warnings). This fully informs the agent of what the tool does and returns.

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

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

Two concise sentences, no fluff. The main action and result are front-loaded. Every word adds value.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all aspects: purpose, usage context, parameter, and return content. It is fully complete for an AI agent to select and use correctly.

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

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

Schema coverage is 100% and the domain parameter is well-described in the schema. The description adds no extra semantics beyond the schema's description. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs a live SPF DNS lookup, returning SPF record and diagnostics. It distinguishes itself from sibling tools like dns_check_dkim and dns_check_dmarc by focusing on SPF and using the phrase 'Live SPF DNS lookup'.

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

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

The description explicitly says it does not require a project and works for any domain, even unmonitored ones. It provides concrete use cases: verify SPF configuration, diagnose DNS lookup issues, or check a domain before adding to a project.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's addition of 'live query', 'returns TTL and type', and 'works for any domain' provides useful context but is not essential beyond annotations.

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

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

Well-structured, front-loaded with the main action, then lists specific use cases. Every sentence adds value, no wasted words.

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

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

Given one parameter and no output schema, the description explains the return format (records with TTL and type) and covers common use cases, making it complete for effective tool selection and invocation.

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

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

Only one parameter (domain) with 100% schema description coverage. Description adds no extra semantic information beyond what the schema already provides.

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

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

Description clearly states it performs a live TXT DNS lookup, returns all TXT records with TTL and detected type. It distinguishes itself from siblings by noting it shows all records, unlike other tools that only see DMARC-reported data.

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

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

Explicitly lists when to use: detecting duplicate SPF records, verifying new DNS records, checking conflicting/stale entries, diagnosing issues. Contrasts with sibling tools (get_spf_records, get_dkim_records) to guide selection.

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

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

Annotations already mark it as read-only and idempotent. The description adds behavioral context about diagnostic capabilities (missing selectors, invalid keys, alignment problems), which is beyond what annotations provide.

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

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

Two short paragraphs with no extraneous text. The first focuses on the resource and outputs, the second on usage guidance. Front-loaded with the key purpose.

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

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

For a read-only tool with full schema coverage and explicit usage alternatives, the description is complete. It covers expected return fields, diagnostic capabilities, and when to use this vs. the full data tool.

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

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

Schema coverage is 100%, so both parameters (domain, project_id) are already documented. The description does not add new semantic meaning beyond the schema, baseline of 3 applies.

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

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

The description clearly states it retrieves DKIM DNS records for a domain, enumerating specific fields (selectors, signing domain, health, etc.) and diagnostics. It distinguishes itself from siblings like dns_check_dkim and get_domain_full_data.

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

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

Explicitly notes that the data is included in get_domain_full_data and recommends calling this tool only when DKIM records alone are needed, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds detailed explanation of the quantile field: 'quantile: 0–1 scale showing where the day's value falls within its 14-day rolling baseline... This value is stable across the period because it is computed over the same 14-day window — this is expected, not a data bug.' This prevents misinterpretation of data behavior.

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

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

The description is front-loaded with the core purpose, then details metric groups and quantile explanation, then bullet-pointed usage cases. Every sentence adds value; no redundancy.

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

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

No output schema exists, but the description thoroughly explains the response structure: four metric groups (spf, dkim, dmarc, volume) each with severity, quantile, and value. It also covers the quantile calculation and the default/max days. Given the tool's complexity and lack of output schema, this is fully complete.

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

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

Schema coverage is 100% so baseline is 3. The description mentions the default (7) and maximum (30) for the 'days' parameter, which adds slight value beyond the schema. But for 'domain' and 'project_id', no additional explanation is provided.

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

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

The description clearly states it returns 'Activity health history for a domain — daily breakdown of SPF alignment, DKIM alignment, DMARC compliance, and message volume over the last N days'. This specifies both the verb (get history) and the resource (domain activity health), distinguishing it from sibling tools like get_domain_full_data and get_domain_detail.

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

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

Explicitly lists four specific use cases, including detecting degradation and explaining severity changes. It also advises typical invocation order: 'Typically called after get_domain_full_data when the health status shows a problem'. This gives clear when/why guidance and mentions alternatives indirectly.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds extensive behavioral context beyond annotations, detailing the specific return fields, anomaly flags, and implications for SPF alignment. It fully discloses the tool's behavior without contradiction.

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

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

The description is well-structured with clear sections: purpose, parameter format, return fields, anomaly flags, and usage guidance. It is front-loaded but slightly verbose in detailing return fields. Nevertheless, it remains focused and efficient for its complexity.

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

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

Given the absence of an output schema, the description thoroughly explains all return fields, anomaly flags, and their interpretations. It provides complete context for an agent to understand what the tool returns and how to interpret results.

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

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

Schema coverage is 100% with both parameters described. The description provides a usage example for domains but adds minimal semantic value beyond the schema. Baseline score of 3 is appropriate.

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

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

The description explicitly states 'Compare yesterday's email authentication metrics against 14-day historical baselines to detect anomalies,' providing a specific verb and resource. It distinguishes itself from siblings like get_domain_full_data by focusing on anomaly detection over historical baselines.

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

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

The description clearly states when to use the tool: 'Use this after get_domain_full_data when you need to compare metrics against historical norms or check multiple domains at once.' It specifies prerequisites and references an alternative tool.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by listing the specific data points included and excluded, giving a clear behavioral profile beyond the annotations. No contradictions.

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

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

Three sentences, front-loaded with the core purpose ('Lightweight domain info'). Each sentence adds unique value: the first lists inclusions, the second lists exclusions, the third gives usage context. No unnecessary words.

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

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

Given the lack of output schema, the description adequately lists the items included and excluded, helping the agent understand the scope. However, it could be slightly improved by noting the response format (e.g., JSON object) or typical fields, but the current level is sufficient.

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

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

Input schema has 100% description coverage for both parameters (domain and project_id). The description does not add any additional semantics or examples beyond what the schema already provides, 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.

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

Clearly states it is a 'lightweight domain info' tool, lists specific items included (DMARC record text, policy, health status, DNS errors, name servers, monitoring status), and explicitly names what is excluded (SPF/DKIM records, timeline, stats) with reference to the sibling tool get_domain_full_data, providing clear differentiation.

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

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

Explicitly states when to use: 'when you only need to check the DMARC record configuration or protection level without heavy analytics data.' Also mentions alternative tool for full data, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already include readOnlyHint=true and idempotentHint=true, so the description does not contradict. It adds value by detailing exactly what data is returned, compensating for the lack of an output schema. However, no additional behavioral constraints (e.g., rate limits) are disclosed.

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

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

The description is well-structured with bullet points, front-loaded with the purpose, and every sentence adds value. It is appropriately sized for the complexity of the tool.

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

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

Given the tool's complexity and no output schema, the description thoroughly covers all returned data categories, explains key fields, and provides usage context. It is complete and actionable for an AI agent.

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

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

Schema coverage is 100%, but the description explains key fields like pctEligibleForPolicy and pctFromKnownSources that are not in the schema. This provides semantics beyond the parameter names and types.

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

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

The description explicitly states 'Primary tool for diagnosing a single domain. Returns everything in one call' and lists all data categories. It distinguishes from sibling tools by recommending preference over narrower tools like get_domain_detail, get_spf_records, etc.

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

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

Provides clear when-to-use guidance: 'after projects_overview or list_domains identified a domain that needs investigation.' Also advises against using it for specific slices and directs to get_domain_activity_health for day-by-day history.

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

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

Annotations (readOnlyHint, idempotentHint) already mark it as safe. Description adds behavioral details: returns top 20 per type with message volume and authentication pass/fail counts. Could mention rate limits or typical response size, but overall good.

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

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

Five well-structured sentences, no fluff. Uses bullet-style listing for filter explanation. Information is front-loaded and each sentence earns its place.

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

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

Covers all necessary aspects: purpose, filter options, return format (top 20 per type with volume and auth counts), and usage guidance. No output schema, but description sufficiently documents return values. Context (annotations, schema) is fully leveraged.

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

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

Schema coverage is 100% (all parameters have descriptions). Description adds value by explaining the source_type filter options ('known', 'unknown', 'forward' and that empty means all types) and clarifies the defaults for stats_period_start/end (14 days ago, yesterday).

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

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

Description clearly states 'List top sending sources (ESPs, ISPs, mail services) for a domain, grouped by source type.' It uses a specific verb and resource, and distinguishes itself from the sibling tool 'get_domain_source_details' by mentioning drill-down capabilities.

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

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

Explicitly provides when-to-use guidance: 'Use this to investigate WHERE email is being sent from — especially when unknown sources appear or compliance is low.' Also gives an explicit alternative: 'To drill down into a specific source... use get_domain_source_details.'

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

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

Annotations already declare readOnly and idempotent. Description adds critical behavior: grouping nuances (e.g., ISP grouping may produce multiple rows per provider+country), comment field explanation for ARC overrides, and filtering details. No contradictions.

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

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

Well-structured with bullet points for grouping and clear notes. Not overly verbose, but could trim some redundant descriptions (e.g., 'Best starting point for investigation'). Front-loaded purpose.

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

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

Given 19 parameters and no output schema, description fully covers all parameters, grouping behaviors, filter options, and return fields. No gaps. Exceptionally thorough.

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

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

Schema coverage is 100%, so baseline 3. Description adds extra meaning: explains group_by enum values, problems_only usage, and the comment's ARC override context. Provides value beyond schema.

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

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

Description clearly states 'detailed per-record view of email sources for a domain' and distinguishes from sibling tools like get_domain_senders or get_domain_stats by focusing on per-record details with grouping/filtering.

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

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

Provides explicit use cases ('investigate specific sending sources, drill down into authentication failures, or analyze traffic') and explains group_by options and problems_only. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already indicate read-only and idempotent. Description adds detailed explanations of computed fields (compliantPct, spfCompliantPct, dkimCompliantPct) and their relationships, going beyond annotations without contradiction.

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

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

Two paragraphs: first introduces purpose and outputs, second explains key fields and provides usage guidance. Concise, front-loaded, every sentence adds value.

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

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

Despite no output schema, the description thoroughly explains the return values and their relationships. Provides sufficient context for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so description need not repeat parameter details. However, it adds value by explaining the output fields and their meanings, which aids understanding of how parameters affect results.

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

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

Clearly states it provides a quick compliance summary for a domain over a date range, listing specific outputs (total messages, SPF/DKIM pass/fail counts, compliance percentages). Differentiates from sibling get_domain_full_data by noting it's a fast numeric check.

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

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

Explicitly advises using this tool for a fast numeric check and recommends get_domain_full_data for complete diagnostics including records, timeline, and health trends.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds context about the specific metrics returned (total, compliant, aligned, etc.), which is sufficient for understanding behavior. No contradictions.

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

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

Three sentences with no waste: first states purpose, second details output, third gives usage guidance. Efficiently structured.

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

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

Despite no output schema, the description lists the returned metrics (total messages, compliant, etc.), which is sufficient for understanding the output. Coupled with annotations and clear param descriptions, it is complete for a timeline tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. Description implies date-range filtering but does not add significant 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.

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

Description clearly states it returns a daily timeline of email volume and DMARC compliance for a domain, listing specific metrics. It distinguishes itself from the sibling get_domain_full_data by noting it is a subset.

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

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

Explicitly tells when to use: to spot trends, volume drops, or compliance changes. Also advises that this data is included in get_domain_full_data, so use this separately only when timeline data alone is needed.

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

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

Annotations declare readOnlyHint and idempotentHint true, so safety is clear. The description adds that results are top 100, and data is not aggregated across source types, which are useful behavioral details beyond annotations.

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

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

Three concise sentences: first states purpose and output, second clarifies source_type requirement and data isolation, third provides usage guidance and practical examples. No unnecessary words.

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

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

Despite lacking output schema, the description adequately describes return format (top 100 locations with lat/lon, country, city, volume, compliance stats). It also covers important context like no cross-type aggregation. The tool's complexity is moderate and everything needed for correct invocation is covered.

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

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

Schema already covers all parameters with descriptions (100% coverage). The description adds meaningful context for source_type: required values, no cross-type aggregation, and a suggestion to use get_domain_senders for guidance. This enriches understanding beyond the schema.

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

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

The description clearly states the tool retrieves geographic distribution of email senders for a domain, returning top 100 locations with volume and compliance stats. It distinguishes from siblings like get_domain_senders which focus on sender lists, not geography.

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

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

Explicitly explains when to use (answer 'where are emails sent from'), mentions required parameter source_type and its values, advises calling get_domain_senders if unsure which type to use, and provides a use case for detecting suspicious locations or confirming infrastructure.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds value by explaining parsedTree structure (include chain with lookup counts, leaf trimming) and diagnostic capabilities. No contradictions.

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

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

The description is moderately concise, front-loading the core purpose and key details. A few extra sentences on diagnostics are useful, but overall it earns its place. Could be slightly tighter.

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

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

Despite no output schema, the description adequately covers what is returned (including parsedTree, diagnostics) and provides enough context for an agent to use the tool effectively. The only minor gap is no mention of pagination or limits, but not critical.

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

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

Schema covers 100% of parameters with descriptions. The description does not add new parameter-specific meaning beyond what the schema provides; it only implicitly confirms the domain context. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves SPF DNS records for a domain, listing specific data points like record text, DNS lookup count, health status, and parsed include tree. It distinguishes itself from siblings like get_domain_full_data (which includes this) and dns_check_spf (likely a simpler check).

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

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

Explicitly states when to use this tool vs. the alternative: 'Included in get_domain_full_data — call this separately only if you need SPF records alone.' Also guides on using parsedTree for diagnosing 'too many DNS lookups' and lists common diagnoses.

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

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

Annotations already indicate safe read operation (readOnlyHint: true, idempotentHint: true). The description adds valuable behavioral details: sorting by severity descending, pagination defaults, and explanations of key fields like dmarcStatus and userOverride. While it lacks rate limit or error information, it effectively discloses functionality beyond annotations.

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

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

The description is well-structured and concise: a one-sentence purpose, a usage line, bullet points for filters, return fields, and key explanations, and a clear next step. Every sentence serves a purpose, and critical information is front-loaded.

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

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

Despite no output schema, the description fully explains return values (name, max severity, etc.) and key field semantics (dmarcStatus, userOverride, parked). It also provides pagination details and a follow-up action, making it complete for a straightforward listing tool.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds functional grouping and clarifies the logic of the 'paid' filter (true/false/omit) and severity values. However, since the schema covers all parameters, the description's added semantic value is moderate, justifying the baseline score.

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

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

The description clearly states the verb 'List' and the resource 'domains in a project', with explicit filtering and pagination capability. It distinguishes itself from siblings by referencing 'projects_overview' as a prerequisite and 'get_domain_full_data' as a follow-up, showing its specific role in the workflow.

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

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

The description provides clear usage context: 'Use after projects_overview to explore a specific project.' It explains when to use this tool for listing/filtering and suggests next steps after finding a domain. However, it does not explicitly state when not to use this tool or compare with alternatives like 'get_domain_detail', 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.

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds detailed behavioral context by enumerating the aggregated statistics returned (e.g., max severity, severity breakdown, policy distribution). This goes beyond what annotations provide, informing the agent about the tool's output structure without contradiction.

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

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

The description is well-structured with a clear opening directive ('START HERE') and bullet points for per-project details. It is concise, with every sentence adding value (purpose, usage flow, output breakdown). No fluff or repetition.

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

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

Despite no output schema, the description comprehensively covers what the tool returns: project info, domain counts, email volume, severity, policy distribution. It also clarifies the tool's role in the workflow (first stop before list_domains). This is sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with all four parameters described. The description does not repeat or enhance parameter semantics beyond what the schema already provides. For example, it mentions dates are optional but does not add new constraints or examples. Baseline of 3 is appropriate.

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

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

The description starts with 'START HERE' and clearly states it returns all DMARC monitoring projects with aggregated statistics. It details what each project includes (project info, domain counts, email volume, severity, policy distribution). It distinguishes from sibling tools like list_domains by positioning itself as the first step for discovering project IDs.

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

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

The description explicitly advises to use this tool first to discover project IDs and identify projects needing attention, then call list_domains. It provides clear context for when to use it, though it does not explicitly state when not to use it or list alternatives beyond list_domains.

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