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

Annotations only say it is a non-read-only, open-world, non-destructive write; the description adds the crucial trait that Meta publishes the form instantly and it can never be edited afterwards, only archived. It also discloses dry_run semantics (sends nothing, renders the finished form) and the exact return shape, which annotations cannot convey.

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?

Purpose and the immutability warning are front-loaded before any parameter detail, which is the right ordering. It is long, but with 14 undocumented parameters nearly every line earns its place; only the parenthetical cross-reference to where page_id errors are explained is slightly expendable.

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 14-parameter mutation tool with 0% schema coverage, the description covers required fields, defaults, error codes, the dry-run safety path, and even restates the return object despite an output schema existing. Nothing an agent needs to invoke it safely 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 description coverage is 0%, so the description carries the full burden and does: it enumerates the accepted standard question types, defines the custom-question object shape with options/key behavior, notes privacy_policy_url requires https, privacy_policy_link_text caps at 70 chars, page_id defaults to the account's single page with named error codes, and explains higher_intent's tradeoff and default.

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 ('Instant Form an der Facebook-Page anlegen') and immediately ties it to the downstream sibling meta_create_ad via lead_gen_form_id. An agent can distinguish it from meta_list_lead_forms and meta_archive_lead_form without opening any 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 an explicit ordered workflow: first dry_run=True, align content with the user, then create without dry_run. It also names the only post-creation alternative (meta_archive_lead_form) and explains why no update path exists, so when/when-not is fully covered.

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