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

Annotations already declare this a read-only, idempotent, non-destructive call, so safety behavior needs no restating. The description adds genuine beyond-schema context: the return is the public REST representation with pagination totals and next/previous links, and content is never silently truncated. It stops short of specifying what happens at the page ceiling (page max 10000) or what an oversized-page failure looks like.

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?

Four dense sentences, front-loaded with the core action and the browse-vs-search switch, with no filler. The semicolon-chained return-value sentence is slightly compressed, but every clause carries information an agent can act on.

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 no output schema and no required parameters, the description correctly takes on the job of describing return shape and pagination mechanics, which it does. Only the vague "publication-filtered relationships and public links" clause and the untested page-limit behavior keep it from being fully self-sufficient.

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 60%, and the description compensates by explaining operational intent for the weaker parameters: q omitted means full browse, page should be incremented to continue, per_page may need lowering for large pages. slug and sort rely on their own schema descriptions, so the combined picture is complete, though the description itself adds nothing for those two.

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?

States a specific verb and resource ("List or search published authors") and immediately names the sibling it is not ("Use get_author for a known ID"). An agent can distinguish it from get_author and search_articles without opening any schema.

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?

Gives explicit selection rules: omit q to browse the whole collection, use get_author when the ID is known, increment page to continue paging, and reduce per_page when a page is too large. Both the when-to-use and when-to-use-something-else conditions are covered.

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