facebook_publish_post

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

Annotations already declare the operation non-read-only and destructive, and the description adds context beyond those flags: posts must be approved, the page is connector-bound, message length is capped at 10,000 characters, idempotency is supported, and an effect claim is verified by Spring. There is no contradiction 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?

One lead sentence captures the core behavior, followed by a compact, clearly structured parameter list. Every line adds information and there is no filler, though the list partly duplicates what the schema already exposes structurally.

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 9-parameter external write tool with an output schema and detailed annotations, the description covers most fields and the approval/idempotency contract. It is incomplete on how to source approval_ref and page_id, what values effect accepts, and what happens when an approval is missing or stale, so an agent would still need to infer some workflow steps.

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?

With 0% schema description coverage, the Args section carries the full semantic burden. It explains all nine parameters, including requiredness, message length, optionality of image_url, and when approval_ref is relevant. However, page_id and message are marked required in the description while the schema lists no required properties, and 'effect' lacks accepted values, so compensation is strong but not complete.

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 opens with a specific action ('Publish') and a concrete resource ('Facebook Page'), and adds useful scoping ('exact ... bound to the authenticated project connector route'). This is enough to distinguish it from sibling platform tools like instagram_publish_post and linkedin_publish_post, though it never names them explicitly.

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 phrase 'approved post' and the approval_ref parameter imply an approval workflow, so usage is somewhat implied. However, the description never explicitly says when to use this tool versus instagram_publish_post or linkedin_publish_post, nor does it explain how approval is obtained or when publishing should be withheld.

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