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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false; the description adds the useful reassurance that no contacts are sent, and warns about retry semantics. It does not explain what the destructive aspect actually is, nor how the 'never retry' warning relates to idempotentHint=true, which an agent could read as permission to repeat the call. That tension is not resolved in the text.

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 short sentences, front-loaded with the action, then the side-effect scope, then the retry prohibition. Every sentence carries distinct operational information and there is no 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?

An output schema exists, so return values need not be described, and the safety profile is largely covered by annotations. However, for a destructive, open-world mutation with nested request objects, the description leaves key facts unstated: what authorization is invalidated, what preconditions or permissions apply, and how operationId/request_key should be handled across the recovery path.

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 50%: read_skills, expected_catalog_version and publication_proposal_id are documented in the schema, while work_id, request_key and the nested request.action/connectionId/operationId are not. The description hints at retry identity but never says whether an existing operationId/request_key must be reused for recovery versus a new one issued for a fresh refresh, which is exactly the semantic the agent needs here.

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 (refresh), resource (CRM connection authorization), and mechanism (one captured provider request), which separates it from siblings like native.genads_crm_connections and native.genads_stop_crm_request. It does not name the recovery sibling (native.genads_recover_crm) explicitly, only describing it, so the differentiation is clear but not fully explicit.

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 an explicit when-not-to-use rule (never start another refresh as a retry) plus the alternative paths (recover the response, or reconnect in GenAds). It lacks positive preconditions for the first call, e.g. what state the connection must be in before a refresh is allowed.

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