Ad Transcript

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

Annotations only flag the call as non-read-only, open-world, non-idempotent and non-destructive; the description adds the costly behavioral detail that matters: credit deduction rules, the confirm=true gate, null-return fallback when no video/transcript exists, and that the read-like POST does not publish to social platforms. It stops short of describing auth/account selection mechanics, which the schema covers.

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 purpose, then cost/confirm behavior, then the no-charge failure case; every sentence carries information. The final sentence about read-like POSTs is slightly tangential but does usefully preempt a write-operation misread.

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 no output schema, the description takes responsibility for return behavior (null when no transcript) and the credit/confirm contract, which is the key completeness gap for this tool. Auth selection is delegated to the account parameter description, which is reasonable.

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 100%, so the schema already documents id, url, account, confirm, and cache_max_age including its enum. The description reinforces the credit/confirm semantics tied to confirm but adds little syntax or constraint detail 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?

States a specific verb (Retrieves) and resource (transcript for a single Facebook Ad Library video ad) plus the two lookup keys (ID or URL). This distinguishes it clearly from facebook_ad_library_ad_details and facebook_transcript without opening either schema.

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 clear context: use when you need a transcript for a video ad by ID or URL, requires confirm=true, and credits are charged only when a transcript is returned. It does not, however, name alternatives such as facebook_ad_library_ad_details for non-transcript ad data.

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