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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false; the description is consistent and adds real context: it creates OR updates an existing contact at a chosen stage, and returns a contact_id. It does not spell out what gets overwritten on an existing contact, which is the main remaining gap for a destructive operation.

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 core action is front-loaded and every clause carries information (qualification gate, batch limit, next step). The emoji/brand prefix and parenthetical asides are slightly wasteful but do not bury the substance.

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 mutation with no output schema, the description covers the essential: what it mutates, the eligibility gate, batch size, and that a contact_id comes back. What it omits is how existing contacts are modified and error behavior when the lead isn't qualified.

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 parameter documentation is already strong. The description still adds value by restating the 20-item batch limit and the qualification constraint that gates which lead_ids are even eligible, and by hinting that stage must come from list_pipeline_stages.

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 concrete verb pair (create or update the contact) and resource (CRM pipeline stage), and anchors it to a known UI action ('igual ao botão Pipeline da tela'). It also names the follow-up sibling enroll_contacts, though the branding prefix adds noise before the actual purpose.

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 preconditions are given (qualified lead, score >= 50, already enriched), a batch cap of 20 per call, and a clear next step ('pode ser matriculado em cadência com enroll_contacts'). The agent knows both when to call it and what to do afterwards.

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