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

Annotations already indicate destructiveHint=true, and the description aligns by using 'Replace'. It goes beyond annotations by disclosing important behavioral specifics: passing existing R2 media URLs is required to preserve assets, and passing an ordered segments array for X/Threads replaces the whole thread chain. These are non-obvious behaviors that an agent must know to call the tool correctly. It does not cover every side effect (e.g., whether omitting a platform target removes it), but the key destructive nuances are disclosed.

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, front-loaded with the purpose, and each sentence earns its place. The first sentence states the action and scope, the second gives a critical asset-preservation rule, and the third handles the complex thread-chain case. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 11 parameters and complex nested structures for eight platform targets, yet the description is brief. It explains the two trickiest behaviors (unchanged media and thread segments) but does not clarify whether the update is full or partial for platform targets—i.e., whether omitting a target removes it. This ambiguity could lead an agent to incorrectly update a post by passing only the fields it wants to change. More explicit guidance on the update semantics would be needed for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the semantic burden. It adds meaning beyond the schema by explaining the concept of unchanged R2 media URLs and the ordered segments array for X/Threads, which are the most complex and error-prone parameters. It does not elaborate on every parameter, but many (e.g., scheduledFor, target arrays) are self-explanatory from their names and the schema structure. The description provides enough guidance for the critical decision points.

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 'Replace' and names the resource 'existing draft or scheduled post', and lists the fields that can be updated (caption, media URLs, schedule, platform targets). It clearly distinguishes this tool from create_post, delete_post, and reschedule_post by focusing on modifying an existing post.

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 implies its use case: modifying existing posts (draft or scheduled). It doesn't explicitly state when not to use it or name alternatives, but the sibling list and the phrase 'existing draft or scheduled post' provide clear context. It also gives specific guidance on how to handle unchanged assets and thread segments, which is practical usage direction.

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