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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: results come in pages, only public followers are returned, and pagination should be user-driven rather than automatic. It stops short of stating page size or whether next_cursor is always present.

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?

Three short sentences, front-loaded with the resource and scope, followed by the two operational rules. No filler, no restatement of the title.

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 simple three-parameter read with no output schema, the description conveys what is returned (ids, public only) and how to continue pagination, which is the essential contract. The remaining gap is page size and whether an empty page signals exhaustion, which an agent would have to discover at call time.

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 baseline is 3, but the description adds real meaning beyond the schema: userName and userId are alternatives (either satisfies the lookup) and cursor is opt-in only when the user requests more. The "without @" constraint on userName lives only in the schema, so nothing is lost but nothing extra is added there.

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?

"Get one page of public follower ids for a single account" states a specific verb, resource and scope, and the word "ids" implicitly separates it from the profile-returning sibling get_user_followers. It never names that sibling explicitly, so the differentiation is left partly to inference rather than stated.

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?

"Provide userName or userId" and "Pass cursor only if the user asks for another page" are concrete when-to-use rules, including an explicit guard against over-paginating. What is missing is any mention of the id-vs-full-profile alternatives or the batch sibling for resolving many accounts at once.

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