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

Annotations only mark this as a non-readonly, open-world, non-idempotent mutation. The description goes well beyond them: it discloses the autopilot-vs-review-mode split ('live at once and answers real people in public' vs 'saved off and a person turns it on in Hub'), per-person throttling ('at most once per person an hour'), Instagram's one-DM-per-comment limit, and the required posts:write / posts:publish scope.

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?

It is front-loaded with the core purpose and every sentence carries information, but the mode/rate-limit sentence is long and em-dash-heavy, which slightly slows parsing of two important operational facts.

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 6-parameter mutation tool with no output schema, the description covers prerequisites, permissions, mode-dependent side effects, throttling, and matching rules. There is no output schema to explain, and nothing an agent needs in order 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%, so the baseline is 3. The description earns above that by adding matching semantics the schema lacks ('Whole words match, in any case'), the default for source, and the reply-selection behavior for comment vs message rules.

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 names a specific verb and resource ('Creates a rule that answers Instagram comments or direct messages containing one of its keywords') and immediately scopes it to the account's own name. An agent can distinguish it from list_autoreplies, update_autoreply, and delete_autoreply 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?

It gives an explicit prerequisite ('Read the account and its posts with list_autoreplies first') and clarifies the two operational modes via source comment vs source message. It does not, however, say when to reach for update_autoreply instead of creating a new rule, so the sibling boundary is only partly drawn.

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