Subscribe a Facebook Page to real-time events

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true), the description discloses critical runtime behavior: Meta may accept a subscription yet record fewer fields than requested, the tool reads the answer back from Meta rather than relying on the 200, and unsupported fields are refused by name with a reason. It also states the credit cost (0). This adds substantial behavioral context not available in annotations.

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 long but densely informative—every sentence earns its place. It front-loads the core purpose (push vs. poll) and then systematically covers each field, followed by the crucial read-back caveat and refusal behavior. While it could be trimmed slightly without loss, the length is justified by the tool's complexity and the number of field-specific nuances.

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?

Given the tool's complexity, the description is effectively complete: it explains why to use it (push vs. poll), what each subscription type delivers, how to read events, the risk of partial field recording, and unsupported field handling. There is no output schema, but the description implicitly covers the response by stating the answer is read back from Meta. No essential information for correct invocation 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?

The schema covers 100% of parameters, but the description goes much further: it explains each enum value in depth ('feed' includes comments/posts/likes/shares, 'leadgen' triggers on form submission), notes that `pageId` can be omitted when only one Page is connected, and clarifies that fields Hermoso doesn't consume will be rejected. This is far beyond what the schema's terse descriptions provide.

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 states a specific verb (subscribe) and resource (a Facebook Page), and enumerates the exact event types (feed, mention, leadgen, messages) with a one-line meaning for each. It also contrasts with polling and references the companion read tool (list_meta_webhook_events), making its purpose unmistakable and clearly distinguishable from sibling webhook tools.

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 explicitly frames when to use it: to switch from polling to push-based event delivery, highlighting `messages` as 'THE ONLY WAY to be told about one' and the 24-hour reply window. It points to list_meta_webhook_events for reading what arrived, and clarifies that unsupported fields are refused, guiding an agent on what fields are valid and why to choose this tool over alternatives.

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