Check BIMI Logo Setup

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces rather than repeats them ('Observation only: nothing is published'). It adds substantial non-schema context: the DMARC enforcement gate, what trust_verified true/false/null mean, that revocation is not checked, that mailboxes is eligibility not a promise, and that Outlook does not support BIMI. The only gap is return shape detail, which is largely covered anyway.

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?

Front-loaded with the trigger scenario and every sentence carries operational information, but the body is one very dense paragraph mixing setup checks, certificate semantics, mailbox eligibility, and generated-record rules; splitting it would improve scanability for an agent.

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

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

There is no output schema, and the description compensates thoroughly: it explains dmarc_sources, the default._bimi record, SVG Tiny PS logo validation, certificate trust states, mailbox eligibility, generated.record/null behavior, status unknown, and next_step. Nothing needed to call or interpret the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by tying logo_url to a downstream consequence (generated.record becomes the exact record to publish at generated.host, present verbatim) and noting certificate_url is only used together with logo_url, which the schema states but the description reinforces with output implications.

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?

Names a specific verb (a live read) and resource (one host's BIMI setup) and leads with the user intents that select it (logo in Gmail/Yahoo/Apple Mail, whether setup works, why logo is missing). No sibling tool covers BIMI, and the description makes that boundary obvious.

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?

Gives explicit trigger conditions (user asking about logo visibility in inboxes), states how to switch modes (pass logo_url/certificate_url to check a candidate logo; omit to check what is published), and includes prohibitions: never compose a BIMI record yourself, and status unknown means retry rather than a broken setup.

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