sapiens_instagram

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

Annotations say readOnlyHint=false and openWorldHint=true, and the description is fully consistent with those. It discloses mutation effects (cria/edita, apaga, responde na mão), permissions (ADMIN-ONLY), API limits (Meta refuses outside the 24h window), and algorithmic behaviors such as round-robin variants and the fallback rule firing only 1x/24h per person. This goes well beyond what the annotations alone communicate.

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 purpose and the admin gate, and every clause contributes to one of the seven actions or the API constraints. However, it is a long, dense run-on paragraph (roughly 250 words) that mixes action semantics, parameter rules, and limitations; better separation would improve scannability. The length is defensible given the 17-parameter/7-action surface.

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, yet the description covers output-oriented details for key actions, such as posts returning id+caption+thumb and inbox conversations exposing canReply based on the Meta window. It also covers required parameter combinations, ID provenance, API restrictions, and edge-case caveats like fallback not firing on comments. For a complex tool, this is a complete enough description for an agent to select and invoke the correct action.

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 already 94%, and the description still adds valuable cross-parameter semantics: keyword+reply are mandatory outside fallback, matchMode and trigger values are explained, mediaId scopes a rule to a post and tells the agent to get real IDs via action=posts, and igUserId comes from inbox. It also clarifies behavioral effects like replyVariants/echoVariants round-robin and fallback never firing on comments, which the schema alone does not express.

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 resource and operation: the Instagram auto-DM engine ('ManyChat próprio') for @sapiensinteticos, and says 'aqui você OPERA esse motor.' It enumerates seven sub-actions (rules, rule_upsert, rule_delete, posts, inbox, thread, send), so an agent can clearly identify what the tool does. This strongly differentiates it from the many sapiens_* sibling tools by resource and action space.

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 states 'ADMIN-ONLY (dono)' and defines the operating context: when DMs or keyword comments arrive, this tool operates the automation engine. It gives concrete workflow hints such as 'pegue ids reais com action=posts' and 'vem do inbox', plus an explicit exclusion: 'não dá pra iniciar conversa, só reagir; janela de 24h pra responder DM.' It does not name alternative siblings, but the action-level routing is strong enough for this domain.

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