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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the '[read]' tag is redundant. The description does add useful context about what is being read (link slots of a single article, one table), but it does not say whether a missing article errors or returns empty, nor what the slots look 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?

Two short sentences, front-loaded with the read marker and the resource, then the invocation hint. The only waste is the '[read]' prefix duplicating readOnlyHint.

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, the description should convey the return shape, but 'internal-link slots' is left undefined — an agent cannot tell whether it gets URLs, anchors, target articles, or counts. Adequate for invocation, thin for interpreting results.

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 description coverage is 0%, so the description must compensate. It does partially: 'Pass X or Y' communicates an either/or selector and implies at least one identifier is needed even though the schema marks zero required params. It does not address precedence when both are supplied or the accepted UUID format.

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 resource: the internal-link slots of one article, plus the backing table name (seliee_articles_links). That is enough to distinguish it from rotate_article_links and list_articles_links_counts, though it never explicitly contrasts with them.

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?

The only guidance is which identifier to supply. There is no statement of when to use this versus rotate_article_links or list_articles_links_counts, and no mention of prerequisites such as the article needing to exist or having link slots defined.

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