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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which covers the safety profile. The description adds that it supports bulk execution (page_ids, post_ids) and the flattened action 'list', but does not mention any limitations, auth requirements, or response structure beyond what is implied.

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 description is concise and front-loaded with 'Read Facebook Pages data.' However, the list of actions is somewhat repetitive and could be more structured. It includes a clutter marker '[Flattened action: list]' which is confusing and not explanatory.

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?

The tool has 6 parameters, no output schema, and no schema description coverage, so the description is the main source of semantic info. It covers the actions and bulk support, but lacks critical details like parameter requirements for each action, return format, and pagination. Sibling tools have specific names (e.g., meta_ads_pages_insights) that may overlap, so more guidance is needed.

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 compensate. It mentions 'period', 'page_id', 'post_id', 'page_ids', 'post_ids' in the actions, but does not explain the meaning of 'auth_account' or the interaction between parameters (e.g., which are required for which action). The bulk support mention adds some value, but it's incomplete.

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 lists multiple actions (list, insights, posts, post_insights) but flattens to 'list', so the primary purpose is to read Facebook Pages data. It specifies the resource (Facebook Pages) and the verb (Read), and distinguishes from siblings like meta_ads_pages_insights and meta_ads_pages_posts, which likely have more specific scope.

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?

The description mentions bulk support and the actions, but does not explicitly state when to use this tool versus siblings like meta_ads_pages_insights or meta_ads_pages_posts. The flattened action implies the default is 'list', but no exclusions or alternative recommendations are provided.

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