Sigil

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

With no annotations provided, the description fully covers behavioral traits: independent lens failure semantics (single-lens returns 200 with confidence 0.55, 503 only when both fail), the 5-minute signed sigil_token, the witnessed_event creation with AIT, and the specific witness identifier. This adds significant context beyond what structured fields would provide.

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

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

The description is longer than typical but well-structured with clear sections: purpose, when to use, inputs, returns, and failure semantics. It is front-loaded with the core purpose and every sentence contributes meaningful information without redundancy 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?

Given the tool's complexity (4 parameters, no output schema, composite behavior), the description covers all essential aspects: per-lens output blocks, fused verdict fields, failure modes, witness chaining, and optional parameters. It is complete enough for an agent to invoke correctly without external documentation.

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

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

The schema has only 50% coverage (weights and thresholds lack descriptions), but the description compensates by explaining each parameter: node auto-detection, threshold defaults (0.7/0.3), AIT chaining behavior, and weight overrides. It adds examples like AS64500 and clarifies free-form objects, providing value 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 identifies the tool as a cross-lens join that fuses Scry attacker intelligence and Sigil supply graph data into a single verdict on a node key. It explicitly distinguishes itself from sibling tools by emphasizing the fused cross_lens block carries information neither lens can supply alone, making the purpose specific and unique.

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

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

The description provides explicit 'Use this tool when' guidelines, including scenarios like making transaction decisions when one-lens answers are insufficient. It also names the alternative of running Scry + Sigil separately and reconciling manually, which implicitly guides when not to use this tool.

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

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

With no annotations, the description must disclose behavior. It does explain validation against a profile, signing, and return, but it omits any side-effect details such as whether the AIT is stored or if re-registration is allowed. 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.

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

The description is well-structured with a clear purpose, a bulleted input list, and a return line. No filler; each part 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, it describes the return value and its use. It covers the main workflow, but could be stronger on error scenarios and the optional parameter. Overall, it's sufficient for an agent to select and invoke the tool.

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

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

The description provides meaningful explanations for all required parameters, including domain-specific constraints (e.g., block_interval_seconds 60-3600, expires_at <=365 days). It omits the optional `agent_type` parameter, which is a gap but minor.

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

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

The description opens with a specific verb ('Register') and resource ('ATAP v0.1 Agent Identity Token') and adds context ('for a media-buying agent'), clearly distinguishing from sibling tools like sigil_atap_witness.

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

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

It explicitly states 'Do this once per agent campaign before witnessing any events,' which tells the agent when to use it relative to the witness tool. It doesn't name alternatives but the timing is clear. No explicit when-not.

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?

With no annotations, the description carries full burden and discloses key behaviors: payload validation with PII rejection, evidence tier classification (anchored vs asserted), constraint violation derivation, and signing. It also states the return values. However, it stops short of stating idempotency, permissions, or failure modes.

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: a dense first paragraph for function, a 'Use this tool when' block, a bulleted Inputs list, and a Returns sentence. No filler; every sentence adds value and the key exclusions are included.

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

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

The description covers purpose, inputs, returns, and an explicit exclusion. For a complex witnessing tool with no output schema, it provides a solid overview. It lacks details on error responses and whether batch submissions are allowed, but the essentials are present.

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

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

Schema coverage is 0%, but the description explains all three parameters: `ait` is an AIT id, `event_type` lists the allowed enums, and `payload` points to the sigil:media_buyer:v1 profile. This compensates for the schema gap, though the payload definition is external.

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

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

The description opens with a specific verb 'Witness' and names the resource ('AIT's hash-chained attestation log'). It also distinguishes from siblings by explicitly noting that supply:verified events come from verify_supply_path, and by listing the four accepted event types.

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

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

It includes an explicit 'Use this tool when' block that lists the condition (ATAP-enrolled media-buyer agent submitting bid/win/loss/budget decrement). It further clarifies the alternative tool (`verify_supply_path`) for supply:verified events, providing a clear exclusion.

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?

With no annotations, the description carries the full burden. It discloses the output format (JSON with receipt_id and zip_base64), that the zip is base64-encoded, and the offline verification step via verify.sh. This goes beyond a simple 'generate' statement, though it does not mention side effects or permissions.

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

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

The description is compact and effectively organized into sections (purpose, usage, inputs, returns). Every sentence adds relevant information without redundancy.

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

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

Despite no output schema, the description fully equips the agent: it explains the purpose, when to use it, parameters, return structure, and how to process the returned data. This is comprehensive for a two-parameter generation 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 0%, but the description compensates by explaining `ait` as 'the AIT id' and `format` with its enum values and default. It clarifies purpose but could elaborate on the difference between 'full' and 'summary'.

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 a specific verb ('Generate') and resource ('ATAP v0.1 compliance Receipt for an AIT'), and explains the artifact's role and verifiability. This distinguishes it from sibling tools that handle registration, witnessing, scoring, or 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?

It explicitly states when to use the tool ('when a reporting period closes and you need a compliance export'), providing a clear scenario. It does not name alternative tools, but the use case is distinct from 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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: scores are 'pre-computed', invalid IDs are 'reported inline, never failing the batch', and custom weights allow 're-score' functionality. However, it doesn't explicitly state whether the operation is read-only or if it has side effects, which is a minor gap.

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

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

The description is well-structured and front-loaded with the core purpose. It uses clear labels ('Use this tool when', 'Inputs', 'Returns') and each sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

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

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

The description covers the primary use case, input format, and return structure (count, scored_count, per-entity results, invalid id handling). However, it doesn't explain what happens if more than 200 IDs are passed or enumerate valid entity types, leaving some edge cases unaddressed. Given the absence of an output schema, this is still a fairly complete description.

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 0%, so the description must compensate. It provides meaningful semantics for both parameters: entity_ids is an 'array of {type}:{domain} ids, up to 200', and weights is 'custom component weights to re-score with.' While the weights structure is vague, the core parameter behavior is clearly explained.

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 provides 'Pre-computed trust scores for up to 200 entities in one call' with a specific use case of 'evaluating many supply sources during campaign setup.' It distinguishes itself from sibling tools like sigil_score_entity by emphasizing the batch capability.

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 a 'Use this tool when' section that gives explicit guidance: 'You have a list of publishers/SSPs to grade at once.' While it doesn't name alternative tools, the batch context clearly differentiates from the single-entity sibling (sigil_score_entity), making the intended usage 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?

With no annotations to provide safety or behavioral hints, the description fully carries the transparency burden. It discloses that scores are recomputed daily, deterministic with 'no ML black box,' based on specific factors (ads.txt health, supply-chain directness, reach, stability), and describes the exact return values including trust_score, score_components, 14-day trend, and warnings. This is highly transparent.

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: the first sentence states the core purpose, followed by a 'When to use' section, then input format, and finally return values. Each section is concise and earns its place. There is no redundant or filler content, and the front-loaded design makes it easy to scan.

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

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

For a tool with a single required parameter and no output schema, the description is remarkably complete. It explains the input format, the output fields with their semantics, and the use case. It also provides important context about the score's computation frequency and deterministic nature, making the tool fully understandable without needing external documentation.

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

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

The schema for entity_id only provides an example. The description adds crucial semantics by specifying the required format `{type}:{domain}` and giving concrete examples such as `publisher:nytimes.com` and `ssp:pubmatic.com`. This goes well beyond the schema and is essential for correct parameter construction.

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

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

The description opens with a specific verb and resource: 'Get the pre-computed trust score for one supply-chain entity (a publisher or an SSP).' It clearly distinguishes itself from sibling tools by emphasizing 'pre-computed' and 'without running checks,' making it unique among the verification and checking tools.

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

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

The description provides an explicit 'Use this tool when' section: 'when you want a fast standing trust signal for an entity without running checks.' This clearly states the intended use case. However, it does not explicitly name alternative tools or state when not to use it, only implying that real-time checks would be done elsewhere.

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?

With no annotations to lean on, the description discloses return structure (supply_paths counts, paths[]), classification semantics (corroborated/contradicted/unchecked), one-level reseller expansion, the in_supply_graph:false edge case, and riskiest-first ordering. It also clarifies that counts cover the full set even when limit truncates. This fully exposes 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?

Although lengthy, it is front-loaded with purpose and differentiation, then usage, then inputs/returns in structured bullets. Every sentence adds needed operational 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?

Given no output schema and no annotations, the description is remarkably complete: it explains what is returned, how classifications are computed, ordering, edge cases, and even the limit/full-set nuance. An agent can invoke this tool with full confidence in the result.

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 both parameters, but the description adds operational meaning: limit default (200) and cap (500), riskiest-first ordering implications of truncation, and that counts are over the full set. This goes well beyond the schema's bare descriptions.

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

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

The description opens with a specific verb and resource: 'Walk the supply graph for a publisher domain and get back the ITEMIZED sell paths.' It explicitly distinguishes this tool from sigil_verify_supply_chain (verifies a schain you bring) and the dark-pool-risk signal (returns counts only), making its unique purpose unmistakable.

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

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

Provides an explicit 'Use this tool when' section with two concrete scenarios (publisher domain without schain, and dark-pool-risk follow-up) and contrasts with alternatives, stating when not to use it. This is exactly the guidance an agent needs.

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?

With no annotations, the description carries full burden and does well: it discloses caching behavior, crawl coverage limits (top ~10k domains), resolve_chain logic, and the return structure. It lacks an explicit statement that the tool is read-only or what happens for domains outside the crawl, but the overall behavioral disclosure is strong.

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: action, usage guidance, inputs, and returns. Every sentence adds value, and the length is appropriate for a 4-parameter tool. It front-loads the core purpose and avoids redundancy.

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

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

Given no output schema, the description adequately lists return fields (verified, confidence, matched entry, warnings). It covers purpose, usage, parameters, and behavior. Minor gaps include explicit read-only confirmation and edge-case behavior for domains not in the crawl, but overall it is complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the purpose of each required parameter, provides examples, and elaborates on the optional resolve_chain parameter (e.g., walking one hop into sellers.json when entry is RESELLER). This adds meaning well beyond the bare schema 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 clearly states the tool's function: checking whether an exchange/SSP is authorized to sell a publisher's inventory via ads.txt. It uses specific verbs ('check', 'authorized', 'validate') and explicitly distinguishes itself from broader supply-path scores, making it distinct from sibling tools like sigil_verify_supply_path.

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

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

The description provides explicit 'Use this tool when' guidance, including a narrow authorization check and validating a (publisher, exchange, seller_id) triple. It also contrasts with full supply-path scoring, effectively communicating when not to use it and pointing to an alternative.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains that the tool returns a `verified` boolean (true/false/null), the store listing, and a `developer_match`, and that it detects spoofing. This gives the agent a good sense of the tool's behavior. It does not detail edge cases like null semantics or network dependencies, but the essential behavioral traits 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 a clear purpose statement, a 'Use this tool when' section, bulleted inputs, and a return summary. It is front-loaded with the core purpose, and each section is concise. No unnecessary words, and the formatting makes it easy to scan.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description provides sufficient context for an agent to decide when and how to use it. It covers the purpose, inputs, and outputs. It lacks some edge-case details (e.g., handling of invalid platform values, return semantics when app not found), but overall it is a complete enough description for correct selection and invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explicitly listing each parameter, marking `bundle_id` and `platform` as required, giving allowed platform values (ios | android | ctv_* | web), and explaining `claimed_developer` as an optional developer name match. This adds meaningful semantics beyond the bare schema. However, it could elaborate more on the meaning of `ctv_*` or the format of bundle IDs, preventing a 5.

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

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

The description clearly states the tool's purpose: verify that a mobile/CTV app bundle ID exists in its app store, optionally checking the developer match. It highlights the specific resource (app bundle ID) and the action (verify), while also mentioning the anti-spoofing use case. This differentiates it from sibling verification tools like sigil_verify_ads_txt or sigil_verify_ip_type, which target different aspects.

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

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

The description gives an explicit usage condition: 'Use this tool when a bid request names an app bundle and you must confirm the app is real.' This provides clear context for when to invoke the tool. However, it does not explicitly mention when not to use it or suggest alternative tools, which prevents a perfect score.

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?

With no annotations provided, the description carries the full burden of behavior disclosure. It adds valuable behavioral traits: "Stateless — the IP is never logged or stored" and explains the detection purpose. It also details return values (ip_type, confidence, ASN + org), which is essential since there is no output schema. It does not mention rate limits or error behavior, but for a stateless read-only classification tool, the disclosed traits are highly relevant and reasonably complete.

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, usage trigger, input, and return values. Every sentence serves a distinct purpose with no redundancy. It is concise yet informative, fitting the tool's simple nature.

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

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

Given the simple one-parameter tool, no output schema, and no annotations, the description is thorough: it states the input, expected output format, and a behavioral guarantee (statelessness). The "Use this tool when" section ties it to the broader bid-request context, making it complete for an agent to decide when and how to invoke it.

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 no description for the `ip` parameter (only an example), and the description's "Inputs" section merely restates that `ip` is required and an IPv4 address. This adds minimal meaning beyond the schema. It does not clarify whether IPv6 is unsupported, whether public/private IPs are handled, or any formatting constraints. Since schema coverage is 0%, the description should compensate more, but the parameter is simple, and the example in the schema partially fills the gap.

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

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

The description starts with a specific verb and resource: "Classify an IPv4 address as datacenter, residential, mobile, or unknown." This clearly distinguishes it from sibling verification tools by focusing on IP classification rather than supply chain or ads.txt verification. It also states the intended use case (detecting datacenter traffic posing as real user devices), adding depth beyond the simple action.

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

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

The description includes a "Use this tool when" section that names a concrete scenario: needing to know whether bid-request traffic originates from a datacenter. It does not explicitly list when not to use it or alternatives, but given the sibling tools are all clearly different (e.g., verify_ads_txt, verify_supply_path), the context is sufficient to guide selection without exclusions.

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

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

With no annotations, the description carries the full burden. It explains the per-node verification process against sellers.json and ads.txt, and describes the output components (per-node results, aggregate verdict, recommendations, sigil_token). This is meaningful behavioral detail beyond the schema, though it does not cover error cases or requirements.

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 short sections for use-case, inputs, and returns. Every sentence adds value: the first sentence establishes the purpose, the 'Use this tool when' gives context, and the Inputs/Returns sections clarify order and semantics. It is concise and scannable.

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

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

Given the tool has nested objects and no output schema, the description provides a complete picture: it explains the input semantics, the verification logic, and the return payload (per-node nodes, verdict, recommendations, sigil_token). This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema description coverage is only 33%, but the description compensates by providing the full structure for `schain` ({ver, complete, nodes:[{asi,sid,hp}]}) and explaining that `site_domain` or `app_bundle` are 'inventory origin' checked against node[0] via ads.txt / OWNERDOMAIN. This adds meaning the schema lacks and clarifies optionality.

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 ('Verify a full OpenRTB SupplyChain (schain) object') and clearly distinguishes from sibling tools by emphasizing 'every node, end to end' and returning per-node and aggregate verdicts. It is not a tautology and names the exact resource.

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 an explicit 'Use this tool when' section: 'A bid request carries an OpenRTB schain and you want it verified verbatim.' It gives a clear usage context but does not mention exclusions or alternative tools, so it lacks a when-not-to-use statement.

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?

No annotations are provided, so the description carries the full burden. It discloses the composition of checks, the optional attestation side effect when `ait` is present, the 5-minute token validity, and the privacy behavior that IP is used for lookup only and never stored. This is thorough and goes well beyond a simple operational statement.

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 somewhat long but well-structured with a purpose statement, explicit use cases, and bullet-like input explanations. Every sentence adds value, though it could be tightened without losing information.

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

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

Given nested objects, no output schema, and a complex domain with sibling tools, the description covers purpose, inputs, return values, side effects, and privacy. It is sufficiently 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.

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

Schema coverage is only 50%, but the description compensates by clarifying the structure of `supply_path` (required/optional fields) and the semantic effect of `ait`. It adds meaning beyond the raw schema, though a bit more detail on formats (e.g., IP address validation) could make it stronger.

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

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

The description clearly states the tool's purpose with a specific verb ('Verify') and resource ('one programmatic ad supply path'), and specifies a composite trust verdict plus signed proof token. It also distinguishes itself from sibling tools that perform individual checks (ads.txt, IP, app bundle) by positioning this as the composite 'core pre-bid 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 provides 'Use this tool when' scenarios (pre-bid confirmation, wanting one call instead of separate checks) and names the alternative (running ads.txt / IP / bundle checks separately). This gives clear guidance on when to use vs. alternatives.

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