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

Annotations already carry the safety profile (readOnly=true, destructive=false, openWorld=false), so the description focuses on semantics that structured fields can't convey: that whole-window counts and engagement_summary come from exact latest-counter totals and should be reused 'instead of summing a returned post page'. It also sets expectations by stating 'no accuracy score is supplied' and explains the consequence of a missing ID. No pagination or retention behavior is restated here, but the schema and mode/limit params cover that.

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?

Front-loaded with the routing rule ('Use when...') and dense with non-redundant content across six tight sentences. The closing analytical instruction about assessing claims against price history is more interpretive guidance than invocation guidance, but it is short and useful.

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?

With 19 parameters, nested text objects and no output schema, the description is expected to carry a lot, and it does explain the returned surface (identity, profile, posts, counts, engagement_summary) and the sampling window semantics. Pagination, retention and the 366-day window are left entirely to the schema, which is acceptable but leaves the definition slightly thin for a tool this complex.

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?

At 79% schema coverage with 19 parameters, the schema does most of the work, so the baseline would be 3. The description adds real meaning for the required author_id, which has no schema description at all, by specifying it must be the internal ID from search_authors and not a handle or X user ID, and it clarifies that reported counts are whole-window rather than page-derived.

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 the resource ('author') and spells out what the call returns: author identity, latest stored profile, posts, whole-window counts and first-page engagement_summary. It also frames the use case ('checking a Crypto Voice's claims, changes of view or discussion of an asset over time'), so the agent knows what job it serves. It stops short of stating how it differs from the sibling get_profile/get_posts, which is the only gap.

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?

Clear when-to-use framing plus an explicit prerequisite chain: take the internal author_id from search_authors rather than an X handle or X user ID. It also names the fallback for the failure case ('A missing internal ID cannot record a handle for coverage review; use search_authors with the exact @handle'). No explicit statement of when to prefer get_profile or get_posts instead, so it falls short of a 5.

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