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

Adds genuinely new behavioral context beyond the annotations: the person is not notified, and the tool is a dry run by default with apply:true required to actually write. These are important traits the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) do not convey. It doesn't mention the plan_id/expiry gate, which is left to the schema.

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?

Three short clauses, front-loaded with the primary action, then the inverse, then the side-effect/dry-run caveat. No wasted words.

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?

No output schema exists, so the description should carry return-behavior context; it does partially (dry run, no notification), but omits the plan_id confirmation flow and profile selection, which matter for a write tool with a dry-run gate. Still largely sufficient given the rich inline schema.

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 100%, so the baseline is 3. The description restates the apply (dry run default) and remove semantics but adds little beyond what the schema already documents, and says nothing about plan_id, profile, or label_id sourcing.

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 ('Put a custom label on one person') plus the inverse operation ('remove:true takes it off'), and ties the operation to the PSID from a conversation. It does not explicitly name the sibling boundary (facebook_create_label / facebook_list_labels), so it falls short of a 5.

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 clarifies that this tool targets an existing person's thread rather than creating or listing labels, and covers the remove/apply toggle. However, it never says when to reach for this instead of facebook_create_label or facebook_list_labels, so usage is only implied.

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

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

Beyond the annotations, it discloses reversibility ('Fully reversible with facebook_unblock_user'), explains the idempotentHint by noting re-blocking 'changes nothing, so this is safe to repeat', and warns about batch partial-failure ('Each PSID gets its own outcome'). It also states a non-obvious permission requirement ('PAGE token with pages_manage_engagement... and the MODERATE task') and the messaging side effect. All disclosures are consistent with the 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?

Four sentences, each earning its place: purpose and effect, reversibility and idempotency, per-item batch outcome, and auth requirements. The core purpose is front-loaded in the first clause, and there is no filler or repetition of schema content.

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 write tool with 4 well-documented params and no output schema, the description covers the essential context: effect, reversibility, repeat safety, partial-failure behavior, and auth. The per-PSID outcome statement hints at the response shape, while plan_id and apply semantics are already fully handled by the schema. Nothing an agent needs to invoke it correctly 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 100% and the input schema already documents each parameter in detail, including apply's dry-run semantics, PSID clarification, plan_id expiry, and profile default. The description reinforces the batch limit and PSID concept but adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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 uses a specific verb and resource — 'Add up to 50 PSIDs to the Page's blocked list' — and states the functional effect: 'they can no longer comment on the Page or message it.' It also distinguishes itself from the sibling set by naming facebook_unblock_user as the reversal, making its role in the moderation family unambiguous.

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 gives clear context for when the tool applies (permanently preventing a user from commenting or messaging the Page) and names facebook_unblock_user as the relevant alternative for reversal. It does not explicitly state when-not-to-use versus other moderation siblings such as facebook_hide_comment or facebook_delete_comment, so it stops short of full exclusion guidance.

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

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

Goes well beyond the annotations by disclosing the PUBLIC visibility of the comment, that it is reversible via deletion, that it is NOT idempotent with a concrete double-post risk and recovery path, and that @[page-id] mentions are subject to Facebook review. The one omission is that it never mentions the apply/plan_id dry-run behavior, so a description-only reader could believe a call always writes — the schema carries that, but it is a notable behavioral gap for a write tool.

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-loads the action and scope, then packs alternatives, idempotency warning, and auth requirements into four tight sentences with no filler. Dense but every clause carries decision-relevant information.

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?

Covers the alternative tool, idempotency, reversibility, auth scopes, and content constraints for a 6-parameter write tool with no output schema. The remaining gap is the dry-run/apply-first default, which is fully documented in the schema but absent from the description.

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 100%, so the baseline is 3; the description earns above that by adding the real constraint that `message`, `attachment_url`, or both are needed (the schema only requires `post_id`), by clarifying the attachment is an https image Facebook fetches itself, and by noting mention pass-through semantics.

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 ("Post a PUBLIC top-level comment as the Page on a post") plus the scope distinction that matters most: top-level vs. reply. It names the sibling to use for the other case, so an agent can disambiguate from facebook_reply_to_comment 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?

Explicit routing: "To answer a comment use facebook_reply_to_comment instead." It also gives a concrete recovery procedure (verify with facebook_list_comments before retrying) and the exact permission/task requirements, which is when-to-use guidance at the operational level.

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

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

Annotations cover safety hints, and the description adds substantial context beyond them: duplicates are possible, nobody is notified, the operation is dry-run by default, and apply:true performs the write. This is exactly the behavioral guidance an agent needs before invoking a non-idempotent create tool.

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 short, front-loaded, and every sentence carries operational value: purpose, duplicate warning, sibling routing, notification behavior, and dry-run semantics.

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 create tool with no output schema, the description still states that it returns the label id and covers the key behavioral risks: duplication, dry-run default, and notification side effects. No critical context is missing for correct invocation.

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 all parameters including name, apply, plan_id, and profile. The description adds useful examples for label names and clarifies apply:true, but does not need to compensate for schema gaps.

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: create a custom Messenger label on the Page, with examples and the returned id. It distinguishes itself from siblings by naming facebook_assign_label for use and facebook_list_labels for checking existing labels.

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?

Explicitly says to check facebook_list_labels first because each call creates a new label, and names facebook_assign_label as the follow-up tool. It also clarifies the default dry-run behavior and how to actually create the label with apply:true.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the dry-run-by-default behavior and the two accepted photo sources with where the bytes come from, which is genuinely useful for a write tool. It stops short of covering permission requirements, rate limits, or what a successful call returns.

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?

Two front-loaded sentences with no padding: purpose first, then photo-source constraints, then the dry-run default. Efficient, though it could have squeezed in the draft/scheduled parameter names it already mentions to tighten the link to the schema.

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 an 11-parameter mutation tool with a nested targeting object and no output schema, the description covers the key decision points (photo source, dry run, draft vs publish, album). The remaining details (targeting, alt_text, page_timezone, plan_id) are fully documented in the schema, so nothing critical 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 100%, so the schema already documents all 11 parameters in depth, including apply, plan_id, targeting, and scheduling rules. The description only restates the photo source and album routing, adding little beyond the structured fields; baseline 3 applies.

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 ('Publish ONE photo to a Page') and the capitalized 'ONE' signals single-photo scope, which meaningfully separates it from the text, video, and story creation siblings. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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 covers the options (caption, draft, scheduled, album) and the important fact that it is a dry run by default, which implies when the tool is appropriate. However, it gives no explicit guidance on when to pick this over facebook_create_post, facebook_create_video_post, or facebook_create_story, leaving the alternative routing to inference.

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

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

Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds a genuinely non-obvious trait: the call is a dry run by default and only performs the write on a repeat with apply:true. That is important behavioral context an agent cannot infer from annotations. It does not warn that repeated non-idempotent calls can create duplicate posts, which is the one annotation-implied trait left unexplained.

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?

Two sentences, no filler, and the content types and publishing modes are front-loaded before the dry-run caveat. Every clause carries information an agent needs to choose a mode.

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 an 11-parameter creation tool with nested targeting and attachments but no output schema, the description covers the modes an agent must pick between and the dry-run/apply contract. The plan_id and apply interplay is pushed to the schema rather than the description, which is acceptable given 100% coverage but leaves the flow slightly fragmented.

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 every parameter, including apply, published, scheduled_publish_time and plan_id. The description only name-drops published:false and scheduled_publish_time as the scheduling knobs without adding format or constraint detail beyond the schema; baseline 3 is appropriate.

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 (Create) and resource (a Page post) and enumerates the content modes it supports: text, link, multi-link carousel, multi-photo carousel. That distinguishes it from most siblings, but it never names facebook_create_photo_post, which overlaps with the photos path, so the boundary is left implicit.

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 supplies the practical selection guidance an agent needs for this tool: publish now, keep as draft via published:false, or schedule via scheduled_publish_time, plus the dry-run-then-apply:true workflow. It stops short of saying when to prefer a sibling such as facebook_create_photo_post or facebook_create_reel instead, so there are no explicit exclusions.

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

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

The description adds substantial behavioral context beyond annotations: three-phase upload, dry-run default, local-file-only restriction, per-Page quota of 30 Reels per rolling 24h, and no unpublish step for PUBLISHED. This is exactly the operational nuance an agent needs and goes well beyond readOnlyHint/destructiveHint.

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 compact and front-loaded: purpose first, then constraints and operational details. Every sentence earns its place, and no information is wasted or buried.

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 (9 params, no output schema), the combination of description and rich parameter documentation covers local-file handling, scheduling, dry-run behavior, and plan flow. However, the description itself does not explicitly state the shape of the result or that a dry run returns a plan_id; the schema implies it through the plan_id parameter, so a small completeness gap remains.

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 100%, and each parameter already carries detailed descriptions. The main description mostly reiterates video_state and the local-file constraint, so it adds little new meaning beyond what the schema provides. Baseline 3 is appropriate because the schema does the semantic heavy lifting.

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 and resource: 'Publish a Facebook Reel' and distinguishes the operation through the three-phase upload protocol and video_state options. It is clearly distinct from siblings like create_video_post or create_photo_post because it names Reels explicitly and describes the protocol-specific local-file requirement.

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 gives clear context for when to use the tool: publishing Reels from a local file, with dry-run default and quota implications. It does not explicitly name alternatives or say 'use create_video_post for feed videos', but the Reel-specific wording and upload protocol are sufficient to guide selection among the siblings.

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

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

Goes far beyond the annotations: irreversible (server cannot delete it), not schedulable, 24h public exposure, apply-overrides-FB_WRITE_MODE behavior, plan_id/confirm_token requirements, and dry-run-by-default. These are precisely the risk facts an agent needs before a write.

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?

Dense but efficient: the core action, the irreversibility warning, the apply/plan_id prerequisite, and the verification pointer are all front-loaded with no filler sentences.

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 mutation tool with no output schema, it covers the critical concerns: irreversibility, dry-run safety, required apply/plan_id, out-of-band token, and how to verify. 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 coverage is 100% and each parameter (apply, plan_id, confirm_token, media_type, etc.) is already richly documented in the schema. The description reinforces the apply+plan_id relationship but adds little syntax/format detail beyond what the schema already carries, so baseline 3 applies.

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 ('Publish a photo or video story on the Page') plus the defining traits (24h public, no scheduling). It is clearly distinguishable from siblings like facebook_create_post and facebook_create_reel by naming 'story' and its one-shot lifetime.

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?

Explains dry-run-by-default, the apply:true + plan_id path to actually publish, and points to facebook_list_stories for verification. It stops short of explicitly contrasting with the reel/photo-post siblings, but the when-to-use and precondition guidance is otherwise strong.

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

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

Annotations only cover safety/openness, so the operational detail here is real added value: the resumable chunked protocol, progress reporting, the fact that URLs are fetched by Meta rather than streamed, and that a finished upload is still an unencoded asset. It does not warn that the call is non-idempotent (a retried upload can duplicate the video) nor explain the apply/plan_id write gate, both of which matter for a mutation tool.

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?

Three tight sentences with the core action front-loaded and no filler; the 'not yet encoded, published' clarification and the dry-run note are each doing work. Slightly under-structured — a fragment ('Dry run by default') closes it while the entire publish/draft axis goes unmentioned.

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 10-parameter, nested-object mutation with no output schema, the description covers the mechanics an agent most needs (upload path semantics, resumability, progress, resulting resource state, dry-run default). Gaps remain around the publish/draft/schedule axis and plan_id workflow, though the schema covers those thoroughly.

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% and the schema already documents the local-path/URL duality, the 256 MB cap, published, scheduled_publish_time and targeting in more detail than the description. The description adds no per-parameter meaning beyond restating the video source modes, so baseline 3 applies.

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?

Specific verb and resource: 'Upload a video to a Page', and it explicitly clarifies the state transition ('a CREATED video, not yet an encoded, published one'). It never distinguishes itself from the obvious neighbours (facebook_create_reel, facebook_create_post, facebook_create_photo_post), so it stops short of a 5.

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?

'Dry run by default' and the local-path-vs-URL split imply when to reach for this tool, but there is no explicit when/when-not and no mention of facebook_create_reel as the alternative for short-form vertical video, nor of facebook_get_video_status after upload. Usage is inferable rather than stated.

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

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

Goes well past the annotations: annotations only flag destructiveHint/idempotentHint, while the description states the deletion is permanent and unrecoverable, explains per-id outcome isolation, clarifies that an already-deleted comment counts as success (consistent with idempotentHint), and spells out the two different Page permissions required for own-comment vs user-comment deletions.

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?

Five tight sentences, front-loaded with the irreversible warning before the safer alternative and the apply/plan mechanics. Every sentence carries either a hazard, an alternative, or a permission fact; nothing is filler.

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 destructive, open-world batch write with no output schema, it covers reversibility, the dry-run/apply/plan_id protocol, batch size guidance (split larger sweeps), per-id result semantics, and permission requirements. An agent has everything needed to call this safely.

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 100%, so baseline is 3; the description still adds the coupling rule that apply:true must be paired with a plan_id from a prior dry run and that the confirmation token exists for irreversible applies. It does not add anything about profile or confirm_token beyond what the schema already says, so it stops short of a 5.

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?

Opens with a specific verb and resource ("PERMANENTLY delete ... comments") plus a hard scope limit of 50, and immediately contrasts itself with facebook_hide_comment. An agent can distinguish this from delete_post or hide_comment 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?

Explicitly names the preferred alternative when reversibility matters ("prefer facebook_hide_comment, which is reversible") and states the mandatory precondition ("Always requires an explicit apply:true together with the plan_id from a dry run"). It also warns that the server default will not apply on its own, closing the main misuse path.

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

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

Annotations declare destructiveHint=true, but the description goes further by spelling out the blast radius ('disappears from EVERY person it was on') and the irreversibility ('cannot be restored'), plus the apply/plan_id workflow. This is concrete behavioral context beyond the structured hints.

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-loads 'PERMANENTLY' for maximum warning impact, then delivers blast radius, the alternative, and the invocation requirement in tight clauses. Every sentence earns its place with zero waste.

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 an irreversible mutation with no output schema, the description covers what is destroyed, irreversibility, the alternative tool, and the required apply/plan_id flow. Nothing an agent needs to call it correctly 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 coverage is 100%, so each parameter is already well documented. The description reinforces the apply+plan_id conjunction requirement, but that is largely a restatement of what the schema already explains; baseline 3 is appropriate.

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 (delete) and resource (custom label from the Page), with scope clarified ('from the Page'). It explicitly contrasts itself with facebook_assign_label remove:true, so an agent can distinguish it from the closest sibling without opening schemas.

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?

Names the exact alternative (facebook_assign_label with remove:true) and the condition that selects it ('to take it off one person'). It also states the invocation prerequisite: apply:true together with a plan_id from a dry run. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds real context beyond them: what is destroyed (text, comments, reactions, shares), that there is no trash or undo, the irreversible-tier confirmation dance, the confirm_token fallback, and an honest UNVERIFIED caveat about Reels. It also warns the agent to re-read the Page afterwards rather than trusting the result.

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 the action, then consequences, then the apply protocol, then the API caveat — each sentence adds a distinct operational fact and none repeat the schema verbatim. Dense but no filler.

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 5-parameter destructive tool with no output schema, everything an agent needs is present: scope limits, irreversibility, the two-step apply protocol, token fallback, and post-call verification advice.

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 100%, so the baseline is 3, but the description adds a cross-parameter constraint the schema states only piecemeal: apply plus plan_id are jointly mandatory for this operation and override the server's write mode. It also flags that the plan expires, which shapes call sequencing.

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?

Opens with a specific verb and resource ("Permanently delete a Page post") plus a hard scope restriction ("the app itself created"), which separates it cleanly from facebook_delete_comment and facebook_update_post. The scheduled-post case is called out explicitly, so an agent knows this is also the cancel path.

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 a clear precondition (always requires apply:true plus a plan_id from a preceding dry run, regardless of FB_WRITE_MODE) and the scenario that selects this tool over alternatives (canceling a scheduled post). It does not name sibling tools such as update_post as the non-destructive alternative, which keeps it short of a 5.

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

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

Goes beyond the annotations by disclosing that the operation is local-only, takes effect immediately, and is recoverable via facebook_save_reply — this actually explains why destructiveHint=false despite being a delete. It does not describe whether deleting a nonexistent id errors or is a no-op, which matters given idempotentHint=true.

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?

Three short sentences, front-loaded with the action and its local scope before the recovery note. Nothing is repeated from the title and every clause carries distinct information.

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 two-parameter local mutation with no output schema, the description covers locality, immediacy, and recoverability. The remaining gap is the shape of the returned deleted record, which the description asserts exists but does not characterize.

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 100%, so both `id` and `profile` are already documented with pattern and default-Page behavior. The description adds only the singular framing ("one local saved reply") and otherwise defers to the schema, matching the baseline for fully documented params.

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?

Names a specific verb and resource ("Delete one local saved reply") and immediately scopes it as local-only ("no Facebook call"), which distinguishes it from any Facebook-side deletion sibling. The pairing with facebook_save_reply as the inverse operation makes the boundary unambiguous.

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 supplies the restore path ("can be restored with facebook_save_reply") and the timing ("applies immediately"), which effectively tells an agent when this is safe to invoke. It stops short of explicit exclusions or a direct comparison to other delete tools, so it is clear context rather than full routing guidance.

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

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

Annotations only declare the generic mutation profile; the description adds authorization (PAGE token with pages_manage_engagement), a permission gate that rejects non-Page comments before any write, preview behavior, and how to revert via a second edit. That is substantive context beyond the structured fields.

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?

Four sentences, front-loaded with the action and its restriction, then preview and auth. Each sentence carries information, though the plan-divergence clause is dense enough to slow a quick read.

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 mutation tool with no output schema, the description supplies the missing pieces an agent needs: required permission, refusal semantics, dry-run/plan mechanics, and reversibility. Nothing essential to invoking it correctly is absent.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the plan-mode preview shows current vs new text and is tied to the apply/plan_id flow, and divergence after a concurrent edit is explained. It still doesn't clarify the profile parameter's role.

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 ('Replace the text') plus resource ('a comment the Page itself wrote') and adds a hard scope restriction that separates it from facebook_update_post, facebook_delete_comment, and facebook_comment_on_post. An agent can select it without opening the 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?

The 'fix a typo in a reply' example and the rule that 'comments by anyone else are refused before any write' give clear positive and negative conditions. It never names a sibling alternative (e.g. delete or reply instead), which keeps it below a 5.

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

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

Explains behavior beyond annotations: local high-water mark per Page, first call defaulting to last 24h, non-advancement when mark_seen is false, and that a truncated section keeps its mark so nothing is skipped. This also justifies the idempotentHint:false despite readOnlyHint:true, and adds a prompt-injection warning about untrusted comment/message content.

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-loads what the tool returns, then the high-water-mark mechanics, then the truncation caveat, then the safety envelope and next-step routing. Every sentence carries distinct operational information with no filler.

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 7-parameter, multi-section read tool with no output schema, the description covers return sections, the `truncated:true` signal, mark advancement, first-call window, and trust boundaries for user content. Remaining details (e.g., exact envelope fields) are the main omission but not operationally blocking.

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 71%, and the description adds real semantics for the key params: `since` omission semantics, `mark_seen:false` peek behavior, and the budget/truncation meaning around `max_comments`. It does not add meaning for `posts`, `profile`, or the two include_* toggles beyond their names.

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 resource and scope: 'What is new on a Page since a point in time, in one call: new comments (and replies) on the most recent published posts, and Messenger conversations updated since then or still unread.' This distinguishes it from the broad listing siblings (facebook_list_comments, facebook_list_conversations) by its incremental, cross-section nature.

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 operational guidance: omit `since` to resume from the stored high-water mark, `mark_seen:false` to peek without advancing, and routes follow-ups to facebook_reply_to_comment / facebook_send_message. It stops short of naming the alternative full-history listing tools or when to prefer them, so no explicit when-not-to-use clause.

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

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

Goes well beyond the readOnly/idempotent annotations: it names the required token type and scopes (pages_read_engagement, plus pages_read_user_content for visitor comments), discloses the 7-day private-reply window, and warns that text comes back in an untrusted-content envelope. That is exactly the security and timing context an agent needs before acting on the result.

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?

Two sentences, no filler. The core action leads, then usage rationale, then the auth and trust caveats in decreasing order of importance. Dense but every clause carries information.

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 compensates by describing what comes back: the comment text wrapped in an untrusted-content envelope and a private-reply-possible flag tied to the 7-day window. Auth requirements are covered, so an agent can call this without further discovery.

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 100%, so the baseline is 3, but the description adds real semantic weight: it explains that replies are only included 'optionally', matching the schema's note that omitting reply_limit skips the replies edge entirely. The profile and comment_id parameters are left to the schema, which documents them well.

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 ("Read one comment by ID") plus two scoping modifiers: optional inline replies and the private-reply eligibility flag. This clearly separates it from facebook_list_comments and the mutation siblings like facebook_edit_comment.

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?

Explicitly prescribes a use case: verify the CURRENT text before moderating, because a comment can be edited or deleted between a listing and an action. That gives a real when-to-use rule, but it never names the alternative tool to call instead for bulk reads (facebook_list_comments) or says when not to use it.

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

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

Adds substantial behavior beyond the annotations: it discloses that this read does not mark the thread as seen, that attachments are never inlined (typed placeholders instead), that the window verdict is derived only from the first page, and that message content is untrusted data wrapped in a labeled envelope. These are safety- and correctness-relevant traits an agent cannot get from readOnlyHint/destructiveHint alone.

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?

Core purpose and scope are front-loaded in the first sentence, and each subsequent sentence adds a distinct trait (window check, untrusted-content envelope, no read receipt). It is dense but slightly overpacked with parentheticals that could be tightened.

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 carries the burden of describing the return shape and does so explicitly — fields, attachment placeholder behavior, and the window flag. An agent has everything needed to call it and interpret the response correctly.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains that `after` continuation pages can only confirm the messaging window open, not closed, which changes how an agent should interpret the parameter's effect on the result. Remaining parameters are left entirely to 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 and resource — 'Read one Messenger thread newest-message-first' — and enumerates what comes back (sender, timestamp, direction, body, attachment placeholders). It is clearly distinguishable from the sibling facebook_list_conversations, which enumerates threads rather than reading one.

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 a concrete precondition use case: call this before facebook_send_message to learn whether the 24-hour window is open, and explains the cursor caveat for continuation pages. It does not state explicit when-not-to-use conditions beyond that, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description's real contribution is the auth requirement ("Needs a PAGE token") and the blocking rule (comments containing a blocked word are hidden automatically), which goes beyond the annotations. It says nothing about what happens if settings were never configured.

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?

One front-loaded sentence that names the action, lists the returned fields, and closes with the auth prerequisite. No filler or redundant restatement of the tool name.

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 usefully enumerates the returned settings and even explains the enum values for the profanity filter (OFF, MEDIUM, STRONG), which is what an agent needs to interpret results. It stops short of covering error/default behavior or the meaning of the messaging flag's type.

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 100% and the single `profile` parameter is already fully documented in the schema, including the default-to-FB_PAGE_ID behavior. The description adds no additional meaning about that parameter, so the baseline 3 applies.

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?

"Read the Page's moderation settings" gives a specific verb and resource, and the parenthetical enumerates exactly which settings (blocked-word list, profanity filter level, messaging flag). The contrast with facebook_set_moderation_settings is implied by the verb "Read," so an agent can tell the pair apart.

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 verb "Read" and the PAGE-token requirement imply a safe inspection call, but the description never names facebook_set_moderation_settings as the mutation alternative or states when to prefer one over the other. Usage is inferable rather than explicit.

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

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

Annotations already declare the safe, idempotent, open-world read profile, so the description focuses on the useful extras: the omitted-argument fallback to the default Page and the concrete shape of the hours field ("[{day, open, close}] ranges"). It stops short of noting permission requirements or error behavior for an unknown profile key.

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?

Two sentences, front-loaded with the core purpose, with the field inventory following. The inline field enumeration is long but earns its place since no output schema exists; minor cost is that the parameter rule is buried at the end.

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, describing the returned fields carries real weight and is done well, and the default-Page behavior is documented. Gaps are small: no mention of failure modes for an invalid Page ID or of what `publish state`/`new-Page-experience` actually mean as values.

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 100%, so both parameters are already documented in the schema; the description largely restates `field_set` semantics and the default-Page fallback. It adds only marginal meaning, such as the concrete hours range structure, so the baseline 3 applies.

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 ("Fetch metadata for one Page") and enumerates the exact fields returned, which separates it from the sibling facebook_list_pages. An agent can tell this is a single-object read versus a collection listing 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?

Usage is only implied: the description explains what each `field_set` value yields, which nudges selection between summary and profile, but it never states when to reach for this tool over siblings like facebook_list_pages, facebook_page_insights or facebook_whoami. No exclusions or prerequisites are given.

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

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

Annotations already establish readOnly/idempotent/non-destructive/openWorld, and the description layers on substantive context that annotations cannot convey: Pacific Time boundaries with an exclusive end so the partial current day is dropped, comparison-window semantics, and `delta.pct` being null when the previous value is 0. The reach caveat (unique audience from Meta's rolling 7/28-day window; other spans report unavailable rather than summing daily uniques) and the `eligible:false` explanation (empty metrics usually meaning <100 followers or a token without read_insights) are exactly the non-obvious failure modes an agent needs.

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?

A single dense paragraph, but it is front-loaded with the purpose and deliverable before the caveats, and each sentence contributes something (metric list, method/delta shape, reach limitation, eligible flag, sibling escape hatch). It is near the upper bound of readable length; breaking the reach and eligible notes into short clauses would improve scanning without losing content.

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?

There is no output schema, so the description must describe the return shape and it does: named metrics, each with a `method` derivation and a `delta` of {abs, pct}, plus top posts with lifetime insights and the `eligible` flag. Combined with 100% schema coverage for all 7 optional parameters, an agent has everything needed to call this correctly and interpret the result.

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 carries the per-parameter burden and baseline is 3. The description adds real value on top by explaining the interaction between `window` and `compare` (the comparison window is the immediately preceding window of equal length) and by making the [since, until) half-open interval and its Pacific Time basis explicit.

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 opening clause names a specific resource and deliverable — a one-call Page performance report over a window, compared against a preceding equal-length window — and enumerates the metrics returned (followers, reach, views, engagement, Page views, top posts). It closes by explicitly distinguishing itself from facebook_page_insights, so an agent can separate it from the sibling analytics tools 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?

The final sentence routes the agent explicitly: "For raw series use facebook_page_insights," which is a concrete alternative with a selecting condition. Defaults for window (last 28 days) and the custom-window requirement are stated. It lacks an explicit when-not clause (e.g., don't use for per-post analysis, use facebook_post_insights), so it stops short of full routing guidance.

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

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

Goes well beyond the readOnly/idempotent annotations: enumerates the default field set, discloses that `comment_count` counts only top-level comments, describes the untrusted-content envelope behavior for non-Page-authored posts, and warns that a permission error usually signals a User token rather than a missing post. This is genuinely actionable behavioral context.

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 is front-loaded, but the final sentence is a dense run-on enumerating every untrusted-envelope case. The density and length cost readability even though most content is substantive.

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 compensates by describing the default return shape, count semantics, the `note` field, and the envelope structure under `post.content` / `<field>.content`. Nothing an agent needs to interpret the response or avoid a token pitfall 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 coverage is 100% so the baseline is 3, but the description adds real meaning: `fields` REPLACES rather than extends the default set, `post_id` must be passed verbatim in composite form, and omitting `profile` falls back to the default Page. It maps the parameters to outcomes rather than restating them.

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?

Opens with a specific verb and resource ("Fetch ONE post by its composite id") and immediately contrasts the id source with facebook_list_posts. The single-vs-list distinction from the primary sibling is unambiguous 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?

Explains when the tool applies (a post id previously obtained from facebook_list_posts) and explicitly offers the `fields` override path as the alternative for requesting different Graph fields. It also explains a permission-error diagnosis (User vs Page token), though it does not state an explicit when-not to reach for a different tool.

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

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

Adds real behavioral context beyond the annotations: a post Graph refuses or that belongs to another Page yields an `error` row rather than failing the whole call, and the export path writes to FB_EXPORT_DIR and returns the path instead of rows. Annotations already cover the read-only/idempotent profile, so this is strong but not quite exhaustive — rate limits or the 25-post cap behavior are not restated here.

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 the purpose and the result shape, then the routing rule, then the export caveat — a sensible gradient. It is dense (backticked field names throughout) but nearly every clause carries information; the sentence on per-post error rows is the only one that could be trimmed slightly.

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?

There is no output schema, so the description carries the return-value burden, and it does: row granularity, the `values` vs `breakdowns` split, error rows, and the export return payload (path instead of rows). Combined with a fully documented schema for a 5-param, nested-object tool, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds meaning on top: it names the default metric set (views, unique viewers, clicks, reactions by type) and frames `breakdowns` as unaggregated, which explains what the metric list actually produces. It does not add syntax or format detail for `profile` or `file_name` 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 and resource ('Lifetime insights for several posts in one call') and pins the output shape ('compact table: one row per post with `values` and unaggregated `breakdowns`'). It explicitly names the sibling it is not — facebook_post_insights — so an agent can route immediately.

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 the concrete selection rule ('Pass `post_ids` or `latest`'), the default behavior when neither is given, and the explicit alternative for the single-post case ('For one post with full summaries use facebook_post_insights'). It also signals when to prefer the file export (long series that would be truncated).

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

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

Beyond the read-only annotations, the description discloses crucial behavior: Graph withholds most reactor identities, `users` may be far shorter than `total` or empty, CARE is folded into LIKE totals, and filtered calls rename the across-all-types figure to `allTypesTotal`. It also flags `users` as an untrusted-content envelope whose `users.content` must be treated as data, never instructions.

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 front-loads the resource and returned shape, then layers in the necessary output-integrity warnings. Although dense, every sentence addresses a real ambiguity or failure mode for this tool.

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 carries the burden of explaining return values and does so: per-type totals, overall total, user list, filtered renaming, and identity-withholding caveats. Pagination and cursor behavior are handled in the schema, so the description is complete for an agent to call it correctly.

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 100%, so the schema already documents all five parameters. The description nevertheless adds important semantic behavior for `type`: when filtered, the count for that type is `totals` and the all-types figure is renamed `allTypesTotal`, never `total`. It does not add comparable detail for other parameters, but the schema covers those fully.

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 and resource: 'Read the reactions on one post,' and details the returned shape (per-type totals, overall total, reacting users). It is clear, but it does not explicitly differentiate this tool from sibling tools such as facebook_list_comments or facebook_post_insights.

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?

Usage is implied by 'Read the reactions on one post' and by explaining how to use the `type` parameter to restrict to one reaction. However, there is no explicit when-to-use/when-not-to-use guidance or reference to alternative tools for related data.

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

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

Beyond the readOnly/idempotent annotations, it discloses pipeline semantics (which states are non-terminal and therefore require re-polling), the ID-type constraint, and an honest UNVERIFIED caveat about Reel IDs on this edge. That is exactly the kind of runtime behavior an agent cannot get from 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?

Front-loaded with the purpose, then the polling rationale and ID caveat in three tight sentences. Slight redundancy with the schema on the video-vs-post ID rule, but no filler.

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 two-parameter read tool with full schema coverage and an output schema, the description supplies everything else an agent needs: state vocabulary, polling cadence, the writer sibling that yields the ID, and an explicit uncertainty flag. Nothing material 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 coverage is 100%, so both parameters are already documented, including the video-vs-post ID distinction and the default Page fallback for `profile`. The description restates the video_id semantics but adds no format detail or guidance on `profile`, so it neither compensates nor detracts — baseline 3 applies.

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 ('Poll where one video stands') and enumerates the exact states returned (uploading, processing, ready, error). It explicitly distinguishes itself from the writer sibling facebook_create_video_post, which returns the videoId prematurely.

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 explicit when-to-use guidance ('read the state here instead of assuming a fresh video is live') plus a concrete loop instruction: for non-terminal states, wait a few seconds and call again. It also names the alternative tool that produces the input, leaving nothing to inference.

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

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

Goes well beyond the annotations: annotations only say destructiveHint=false and idempotentHint=true, while the description explains *why* — the comment stays visible to its author and friends but not everyone else, nothing is destroyed. It also discloses partial-failure semantics ('each id gets its own outcome'), deleted-comment idempotency, and the exact token/scopes required (PAGE token, pages_manage_engagement, MODERATE task).

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?

Four sentences, front-loaded with the action and batch limit, then reversibility, then alternative, then failure/permission notes. The parenthetical `hidden:true`/`hidden:false` mapping is compact and no sentence is filler.

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 mutation tool with no output schema, it covers semantics, reversibility, partial failure, and auth. The one meaningful gap is that it never mentions the dry-run/apply workflow, so an agent must read the `apply` and `plan_id` schema descriptions to know a call may not actually write — acceptable given 100% coverage, but a sentence here would close the loop.

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 100%, so the baseline is 3; the description still earns a bump by stating that each id returns its own outcome and by advising to split larger sweeps across calls rather than lowering maxItems. The `hidden` mapping and the 50-item cap are restated from the schema rather than adding new detail, and the apply/plan_id dry-run flow is left entirely to 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 pair (hide/unhide), the resource (comments), and a concrete batch bound (up to 50) in the first clause. It also distinguishes itself from the nearest sibling by name (facebook_delete_comment), so an agent can route correctly 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?

Explicitly frames hiding as the reversible moderation verb and instructs 'prefer it over facebook_delete_comment', giving both the condition and the alternative. It also flags the batch-splitting rule for sweeps larger than 50, which is exactly the operational guidance an agent needs.

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

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

Adds real context beyond the annotations: idempotent skip-if-already-liked behavior, per-id partial failure ('each id gets its own outcome'), reversibility, and the exact permission (pages_manage_engagement with a PAGE token). The notable omission is any hint of the dry-run/`apply`/`plan_id` safety protocol, which is the most consequential behavior for a write tool.

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?

Four short sentences, zero waste, front-loaded with the action and the 50-comment scope. Every sentence carries a distinct operational fact (mode, reversibility, idempotency, per-id outcomes, auth).

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?

Covers batching limits, partial-failure semantics, auth requirements, and reversibility for a 5-param mutation tool with no output schema. The only missing piece is signaling that a write may not occur without `apply`/`plan_id`, which the description leaves entirely to the schema.

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 explains apply, plan_id, profile, unlike, and comment_ids fully. The description only echoes the `unlike` flag and the 50-id cap, both of which are already in the schema, and says nothing about apply/plan_id.

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 ('Like up to 50 comments as the Page, or unlike them') and immediately incorporates the mode flag. An agent can tell this apart from facebook_hide_comment, facebook_delete_comment, and facebook_reply_to_comment without opening the 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?

'or unlike them with `unlike:true`' gives explicit mode selection, and the skip semantics tell the agent how to interpret no-op outcomes. However, it never names an alternative tool or says when to prefer this over other comment moderation tools, so a small inference gap remains.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds value beyond that by disclosing the page-at-a-time pagination model and the full set of returned fields, which is the main behavioral unknown for a list tool. It does not mention permissions on the Page or rate limits, keeping it just below 5.

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?

Two sentences, front-loaded with the verb and resource. The field enumeration is long but each field listed is information an agent would otherwise have to guess (no output schema). Slight density cost but no wasted framing.

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 carries the return-shape burden and does so well by naming the fields including the `id` needed downstream. Pagination and cursor expiry are handled in the schema. Missing are ordering guarantees and any Page-level permission note, minor for a read-only list.

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 100% and each of `after`, `limit` and `profile` is fully documented in the schema, including cursor expiry and defaults. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 ('List a Page's photo albums') with the pagination scope ('one cursor page at a time') and enumerates exactly what is returned. It also names the sibling it feeds into, so an agent can distinguish it from facebook_list_photos and facebook_list_pages.

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?

Clear usage context: call it to enumerate albums, then pass the returned `id` as `album_id` to facebook_list_photos. That chaining guidance is explicit. It lacks an explicit 'do not use when…' exclusion (e.g. use facebook_list_photos to go straight to photos), so it stops short of the top mark.

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

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

Goes well beyond the readOnly/idempotent annotations: it names the exact token and scopes required and, critically, discloses the silent-failure mode where a user token yields an EMPTY list rather than an error (surfaced only as a note). It also warns that comment text arrives in an untrusted-content envelope and must be reported, not obeyed — a genuine behavioral disclosure the schema cannot carry.

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-loads purpose and default ordering, then key parameters, then prerequisites and the safety warning in descending order of importance. Dense but every clause carries information: no filler or restated title.

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 7-parameter read tool with no output schema, it covers auth, failure modes, pagination entry points, and content-safety handling. It stops short of describing the returned comment fields or pagination envelope (nextCursor), which the agent must infer from the schema, but nothing critical 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 100%, so baseline is 3. The description restates filter and include_summary semantics that the schema already documents in equal or greater detail, adding no extra syntax or format guidance for object_id, after, or profile.

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 (list comments) plus the target set (post, photo, video, or another comment) and the default ordering. This clearly separates it from facebook_get_comment (single comment), facebook_triage_comments (moderation queue), and facebook_reply_to_comment (write).

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 concrete selection criteria for the two filter modes and explains when to pay for include_summary. It does not name sibling alternatives such as facebook_get_comment for a single comment, so routing to the wrong tool is still possible, but the within-tool usage guidance is solid.

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

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

Annotations already cover read-only/idempotent safety, but the description adds a real behavioral constraint: snippets and participant names are untrusted and wrapped in a labeled envelope, and should be treated as data. It doesn't mention rate limits or long-polling cost, but for a read tool that is a minor 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?

Three sentences, each carrying distinct weight: scope and return fields first, the operational pattern and alternative second, the safety note last. No wasted text.

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?

No output schema exists, and the description compensates by enumerating the returned fields and the envelope wrapping. Pagination and cursor expiry are handled by the schema, so the description is largely complete, though mentioning that results are paginated in the description itself would help an agent plan the polling loop.

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 100%, so pagination (after/limit), profile, and user_id are already fully documented in the schema. The description restates that user_id is a PSID filter, which adds little beyond what the parameter description already says. Baseline 3 is appropriate.

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 ('List Messenger conversations for a Page'), names the returned fields, and explicitly excludes Instagram threads, which distinguishes it from generic listing siblings. An agent can tell it apart from facebook_get_conversation without opening the 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 workflow (poll and diff updated_time/unread_count to find threads needing a reply), names the follow-up tool (facebook_get_conversation), and explains the user_id narrowing case. Nothing is inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by naming the required token scopes, the MESSAGING task and the accepted Page Contact Terms, plus the fact that labels tag threads in the inbox label view.

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?

Two sentences, no filler. The core listing behavior and its psid variant come first, and the auth constraints follow, which is the right order for an agent deciding whether it can call this.

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?

Return fields (id and name) are stated despite there being no output schema, and the auth prerequisites are fully enumerated. Pagination is delegated to the schema, and edge cases such as an empty label list are not covered, but nothing essential to a correct call 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 100%, so psid, after, limit and profile are already documented in the schema. The description only restates the psid behavior ('the labels on one person') and adds nothing about cursor, limit or profile semantics, so the baseline 3 applies.

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 (List) and resource (the Page's custom Messenger labels), plus the exact shape of each item (id and name). It also carves out the psid variant, which clearly separates it from create_label, delete_label and assign_label in the sibling set.

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 explicit context for both modes: no psid = all Page labels, with psid = labels on one person. Prerequisites (Page token, pages_manage_metadata, MESSAGING task, Page Contact Terms) tell the agent when the call will fail, but no sibling is named as an alternative.

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

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

Beyond the annotations, the description discloses important behavioral traits: it reads exactly one window of up to 100 Pages, does not follow a cursor, and never returns Page access tokens. It also explains how to interpret hasMore, which is crucial for avoiding false conclusions about missing Pages.

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 front-loaded with the core purpose, then adds two high-value caveats about token privacy and incomplete pagination. Every sentence earns its place and no wording is wasted.

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 zero-parameter, read-only listing tool with no output schema, the description supplies enough return-field detail and a critical pagination warning. It gives the agent everything needed to call the tool and avoid misreporting a Page as 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 tool takes zero input parameters, so there is no parameter semantics to clarify. The description appropriately focuses on return behavior and pagination constraints instead.

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 and resource: list the Facebook Pages the operator administers via /me/accounts. It also names the returned fields (id, name, category, granted tasks, token availability), making it clearly distinguishable from single-Page tools like facebook_get_page.

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 gives clear operational guidance for using the result: hasMore true means the list is incomplete, so a missing Page may still exist and should be addressed by raw Page ID. It does not explicitly name alternative tools such as facebook_get_page or facebook_whoami, so it stops short of full when-to-use/when-not guidance.

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

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

Annotations cover the read-only/idempotent profile, yet the description adds substantial context beyond them: the deliberate deviation from Graph's "profile" default, the MODERATE task requirement and how to interpret permission errors, cursor expiry behavior, and the untrusted-content envelope for `tagged` results.

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 and selection rule, then layered detail. One dense paragraph is efficient, though the envelope and permission notes make it long; every sentence still carries actionable information.

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?

No output schema exists, and the description compensates by listing the item fields and, for `tagged`, the envelope shape. Permissions, pagination, and safety context are all covered, so an agent has what it needs to call correctly.

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 100%, so the baseline would be 3, but the description adds value by explaining why `type` defaults to "uploaded", where `album_id` values come from, and the mutual exclusion constraint. It also enumerates the returned item fields, which helps parameter interpretation.

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 ("List photos") and immediately splits the scope into album listing via `album_id` versus Page listing via `type`. It names the sibling it depends on (facebook_list_albums), so an agent can distinguish it from related 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?

Explicitly states the selection rule: use `album_id` when available, otherwise pick `type`, and that the two are mutually exclusive. Missing only explicit routing away to other tools (e.g. use get_page for profile metadata), but the core when-to-use conditions are clear.

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

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

Beyond the read-only/idempotent annotations, it discloses crucial behavioral limits: ranked edges return only about the most recent ~600 posts per year, pagination can end without complete history, Reels and scheduled posts are excluded, and feed/tagged results arrive as an untrusted-content envelope. This is exactly the kind of context an agent needs before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.