domaindrift

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

Annotations declare readOnlyHint=true, which establishes safety. The description adds 'Public and keyless' (authentication requirements) and 'live count' (real-time behavior), which are useful behavioral traits beyond the annotation. This adds context about access and data freshness without contradicting the annotation.

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 two sentences long, front-loads the core concept ('rolling 24-hour aggregate rollup'), and provides a list of example metrics. It avoids redundancy and keeps the text tight, though 'tape legs' could be more explicit, it does not detract from conciseness.

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

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

The tool is simple (no parameters, no output schema), and the description covers the main return content: named categories with counts and the live count aspect. It doesn't detail the exact response format, but given the simplicity, the description is sufficiently complete for an agent to understand what the tool returns.

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

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

The tool has zero parameters, and the schema is empty. The baseline for 0 parameters is 4, and the description correctly avoids inventing parameters. No additional parameter semantics are needed.

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

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

The description clearly identifies the tool as a rolling 24-hour aggregate rollup with specific metrics (DNS provider changes, CA switches, mail moves, unreachable domains). It conveys the resource and what counts are provided, but it does not explicitly differentiate from the sibling tool 'whats_changed_today', so it doesn't fully distinguish from alternatives.

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

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

The description includes 'Public and keyless', indicating that no authentication is required, which is a prerequisite. However, it provides no guidance on when to use this tool versus sibling tools like 'whats_changed_today' or 'lookup_domain'. There is no mention of exclusions or alternative scenarios, so usage guidance is minimal.

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

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

Beyond the readOnlyHint annotation, the description discloses key behavioral traits: throttling (1 req/15s per IP), shared daily ceiling for keyless calls, and authentication via API key for complete records. No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the main purpose, and every sentence adds necessary detail without redundancy.

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

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

With no output schema, the description compensates by enumerating the returned data elements, explaining authentication options and rate limits, providing a complete picture for a single-parameter lookup tool.

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

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

The schema already documents the 'domain' parameter with 100% coverage, and the description does not add parameter-specific semantics beyond contextualizing its usage. 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 'the latest signed observation of one domain' and lists specific data elements like nameservers, mail, CDN, certificate info, etc., distinguishing it from sibling tools that have different focuses.

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

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

The description explains when to use the tool (looking up a single domain's observation) and contrasts keyless vs authenticated access, but does not explicitly mention when not to use it or suggest alternatives among siblings.

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

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

Beyond the readOnlyHint annotation, the description discloses auth requirements ('Public and keyless') and a verification step ('Verify the signing key against /.well-known/domaindrift-keys.json'), which are meaningful behavioral traits. No contradiction with annotations.

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

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

Two compact sentences, front-loaded with the core action and output, followed by trust/verification context. No redundant wording or filler.

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

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

For a simple one-parameter read-only lookup with no output schema, the description is complete: it specifies the input (id), the return contents (commitment fields), and an important verification behavior. No critical context is missing.

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

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

The schema already provides 100% coverage for the single 'id' parameter. The description adds little beyond restating that resolution is by id, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb ('resolve') with a specific resource ('DomainDrift provenance receipt by id') and clearly states the output contents (Ed25519 commitment: output hash, signing key, timestamp, chain link). It also distinguishes from siblings by emphasizing the receipt-based lookup and keyless verification.

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

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

The description gives clear context: use this to resolve any DomainDrift receipt by id, and it is public/keyless. It does not explicitly name alternatives or when-not-to-use, but the 'Public and keyless' plus verification instruction provides useful usage framing.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful context: the keys are public and keyless (no credentials required), and they include derivation paths and validity windows. This gives the agent a better sense of what to expect without needing additional discovery. No contradiction with the annotation.

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

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

Two sentences with no redundancy. The first sentence states what the resource is, the second gives the intended use and access characteristics. Every word 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?

For a parameterless, read-only resource with no output schema, the description is fully sufficient. It covers the resource content, its provenance, and the intended application (offline verification). No additional context is needed for the agent to invoke or use it correctly.

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

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

The input schema has zero parameters, so there is nothing for the description to add. The baseline of 4 applies because with no parameters, the schema is trivially complete and the description need not explain any parameter details.

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

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

The description clearly identifies the tool as providing Ed25519 public keys that sign DomainDrift observations, including derivation paths and validity windows. It also states the intended use case (verification), which clearly distinguishes it from sibling tools like lookup_domain or resolve_receipt.

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 when to use the tool ('verify receipts and signed records offline') and notes that it is public and keyless, implying no authentication is needed. It does not mention when not to use it or name alternatives, but the context is clear enough for the agent.

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 only mark readOnlyHint, and the description adds useful behavioral context: it's public/keyless, returns a ranked top-20, covers the last 24 hours, and is a digest rather than the full change feed. This goes beyond bare read-only semantics without contradicting annotations.

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

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

Two sentences pack a high information density: content type, ranking, time window, security context, and a reference to the fuller endpoint. No fluff.

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

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

For a parameterless, read-only digest tool with no output schema, the description covers what, when, and why, and even mentions the alternative for more complete data. This is fully adequate.

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

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

The input schema has zero parameters, so the baseline is 4. The description doesn't need to explain parameters since none exist.

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 this is a daily digest of significant internet infrastructure changes (DNS, TLS, WHOIS) over the last 24 hours, with a ranked top-20 format. This specific verb-plus-resource makes it distinct from sibling tools like lookup_domain or signing_keys.

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

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

It notes the tool is 'public and keyless', implying it's the easy-access version, while the complete change wire with sync cursors is available via a keyed endpoint. This provides some guidance on when to use this digest versus the fuller endpoint, though it doesn't explicitly name alternative tools.

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