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

The description frames the operation as a 'Read' of saved data, yet the annotations declare readOnlyHint=false and destructiveHint=true; the description never explains what the destructive or side-effecting component is, nor that the call is idempotent. It partially mitigates this by describing the fresh-check mechanism, the 24-hour availability window, and identity constraints ('no default identity, arbitrary source IDs or raw rules'), but an agent would still reasonably assume a harmless read. This mismatch between the read framing and the destructive annotation is a material transparency 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 purpose is front-loaded and there is no filler, but the prose is telegraphed and run-on ('no default identity, arbitrary source IDs or raw rules' is a fragment that requires inference). Four dense sentences pack distinct rules (fresh check, 24-hour window, eligibility caveat, identity constraint) without separating them, which makes scanning harder than necessary.

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 an output schema present, return values need not be explained, and the annotation set covers safety hints, so the description's main obligations are invocation context and the destructive-behavior caveat. It supplies useful domain caveats ('availability is not engagement eligibility') but is thin for a six-parameter, nested-object tool with 50% schema coverage and a destructive hint it never addresses.

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%, and the description adds real meaning for source_kind by tying valid values to sources surfaced in a complete check, and for account_id by warning against a default identity. It says nothing about work_id, request_key, or the read_skills proof array, leaving several required parameters to the schema alone. That is adequate but not compensating for the coverage 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 names a specific verb and resource: reading saved Page, professional Instagram, or advertiser video engagement sources, either latest or exact. That is more specific than a tautology and enough for an agent to distinguish it from generic source tools like genads_identity_sources or genads_read_source_page. It stops short of a crisp one-line statement of what a 'source' is in this catalog, so it is clear but not maximally sharp.

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 routes the agent to a sibling for the fresh-check case ('Request a fresh check with genads_ad_action action engagement_sources and sourceKind') and adds a selection rule ('Choose only available sources from a complete check within 24 hours'). What is missing is an explicit statement of the inverse: when a saved/latest read is preferable to any other sibling, or prerequisites such as needing a prior complete check before calling at all.

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