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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true and destructiveHint=false, and the description corroborates these by explaining the paid external call and the onceKey idempotency semantics ('same key/same input never reruns, changed input conflicts'). It adds real operational context (required marketing:measure plus marketing:read and Marketing-write rights, persistence of model/answer/citations/usage, explicit exclusion of advertising or budget writes), but leaves the webSearch behavior and the response shape undisclosed.

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?

Dense but front-loaded: the core action and its paid/tenant-attributed nature lead, followed by preconditions, idempotency, retry policy and persistence. Every sentence carries operational weight, though the closing negation list and the 'this is an API probe' clarification partially overlap and could be tightened.

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 costly, credentialed write operation with no output schema, the description covers authorization, human-confirmation, idempotency, retry prohibition and what gets persisted, which is the essential set. It stops short of describing what the caller receives back beyond the persisted fields, and never explains the webSearch toggle, leaving a visible gap for a 7-parameter 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%, so the description must carry the load, and it does for most fields: it explains question/locale, brandNames and domains as the measured set, onceKey's stable-unique and conflict semantics, and confirmModelUsage as the usage acknowledgement. The webSearch parameter (a default-true boolean that changes probe behavior) is never mentioned, so one of seven parameters remains semantically opaque.

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?

States a specific verb and resource ('run one paid, tenant-attributed, centrally budgeted OpenAI API discovery probe') plus the target input ('supplied neutral question/locale') and what is measured ('brand aliases/domains outside the prompt'). It also explicitly bounds the tool ('This is an API probe, not a measurement of all consumer ChatGPT answers'), which separates it from the get_ai_visibility* readers without naming them.

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 strong conditions: ask for human instruction before invoking, confirmModelUsage=true must be set, and ambiguous/processing outcomes must not be retried. It does not point to a sibling for reading results or for observational recording, so routing among the visibility tools relies on inference, but the when-to-use conditions themselves are explicit.

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