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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered structurally; the description reinforces it briefly with "Safe read-only." The genuinely additive disclosure is that a revision is returned even for empty, expired, or dismissed editions — a non-obvious behavior that prevents the agent from assuming an error or empty response.

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, front-loaded with the resource and its payload, followed by the revision contract that motivates the call. Nothing is redundant; every clause carries information about output or workflow.

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 must convey what comes back, and it does list the four components plus the edge-case revision behavior. It does not describe shape, pagination, or size of the article list, but for a zero-parameter read tool this is nearly complete.

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?

The tool takes zero parameters, so the baseline is 4 and there is no schema semantics to compensate for. The description spends its words usefully on the return contract instead of inventing parameter details.

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 a specific verb+resource pair ("Returns the authoritative edition state") and enumerates exactly what comes back: publication metadata, article list, and revision number. It also scopes the resource to the user's curated edition ('Deine Zeitung'), which distinguishes it from siblings like get_edition_candidates or get_digest.

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?

It gives a concrete downstream use case — the returned revision "must be passed as expectedRevision when calling publish_edition" — which tells the agent exactly why and when to call this first. It stops short of explicitly excluding alternatives (e.g., when to prefer get_edition_candidates), so it is clear context without full routing guidance.

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