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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description goes far beyond by disclosing the two-call confirmation protocol (call 1 returns 202 with data.preview plus data.confirmation.token, call 2 with the token executes exactly what was previewed), the required reports:write permission, the sign-in prompt for unconnected members, the 429 GRANT_BUDGET limit, and the fact that submitted reports cannot be read back.

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 facts are front-loaded, but the confirmation flow is explained twice (once mid-paragraph, again in the closing block) with near-duplicate phrasing about the token working alone or with the same arguments. The error-code roll-call (409 OWN_POST / OWN_COMMENT / OWN_PROFILE, 404, 409 ALREADY_REPORTED, etc.) is dense to the point of impeding scanning, so the definition is longer than it needs to be.

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 an 8-parameter, non-idempotent, confirmation-gated action with no output schema, the description covers essentially everything an agent needs: permissions, the 202 preview contract, the token lifecycle, budget limits, and the refusal taxonomy. The only soft spot is that the preview/token response shape is described in prose rather than precisely, but no return schema exists to lean on.

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, but the description adds real conditional routing the schema does not express: itemType+itemId are paired only for comment reports, peerId only for message reports, and reason is required for comment/profile but forbidden for posts. It also clarifies details is the member's own words, capped at 255 for posts. Minor cost: it says 255 while the schema allows 2000 generally, which is only reconciled by the schema's own per-case note.

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 first sentence gives a concrete verb plus every resource it touches (post, comment, message, profile) and names the recipient of the report (Automate America's staff, on the member's behalf). The enumeration of site-level report surfaces (post, comment in a feed thread, received message, professional/company profile) makes it unmistakable against siblings like comment_on_item or send_message.

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 states explicit when-to-use conditions per report type, the alternatives/entry points each maps to (itemType + itemId for comments, peerId for received messages), and hard constraints: one thing per call, max 5 reports/day, token single-use and 5-minute expiry. It also lists when-not cases by name (own content, unseen content, duplicates, company directory listings, message reports not offered).

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