List publications

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

Annotations already declare readOnlyHint=true, so safety is settled; the description instead adds non-obvious operational context: sorted newest first, a truncated projection, and the full state vocabulary with the domain mapping that 'ready' means scheduled and 'sended' means published. It stops short of stating pagination behavior for a list that caps at 50 per call.

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?

Two sentences, no filler: the first front-loads what the tool returns, the second handles the alternative and the failure case. Nothing is redundant with the title or restates the name.

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?

An output schema exists, so return values technically need no explanation, yet the description helpfully names the projection anyway. The gap is pagination semantics for limit (max 50) and offset on a list tool where an agent must know how to page — the description says 'newest first' but not how to continue past the first page.

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 63% and the schema itself documents state (including the ready/scheduled alias), search, both dates and id_organization, so the description only needs to compensate for limit, offset and social_network — all of which it leaves untouched. It does add meaning to the state values by enumerating their lifecycle, which the schema lists but does not explain. Baseline 3 is appropriate given the mixed coverage.

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?

Concretely names the resource (posts of an organization), the default ordering (newest first), and the exact projection returned (id, network, state, date, first words of text). It also routes to the single-record sibling, get_publication, so an agent can separate it from the other list_* tools in this server without opening a 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?

Explicitly names get_publication as the alternative and gives the selecting condition ('the full record of one, including why it failed'), which is exactly the when-to-use guidance that matters. It does not address how the filter parameters (state, dates vs. search) should be combined, so the guidance is incomplete but clear.

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