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

Annotations only cover readOnly/openWorld; the description adds genuinely non-obvious behavior: failed calls returning {"error": …} still appear and params shows input not result, restricted sources only see their own entries (gefiltert field), entries are deleted after 24 months so an empty result may mean expired rather than unchanged, and invalid kind values silently fall back to all entries.

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?

Purpose is front-loaded, then caveats, then per-parameter notes in a scannable order. It is on the long side and could be tightened, but nearly every sentence carries operational information rather than filler.

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 four undocumented params, an output schema, and only minimal annotations, the description supplies everything an agent needs: what entries look like (herkunft, params, actor, gefiltert), retention limits, and full parameter behavior. Little is left to guess.

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 0%, so the description carries the full burden and does: days = lookback period (default 30), limit = max entries (up to 200), kind = 'note'/'auto' with other values ignored, workspace = customer slug optional when a single workspace exists. It also supplies the enum values the schema lacks (kind is an unconstrained string in the schema).

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 ('Änderungsjournal des Workspace lesen') and immediately enumerates the two entry types (automatic write-tool logs excluding dry-runs, plus agent notes), ordered newest first. This is clearly distinguishable from the writing sibling journal_add_note and from any analytics tool.

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 concrete usage contexts ('für Wochenreports', attributing performance dips to specific changes), which tells the agent when this is the right tool. It does not explicitly name an alternative sibling or state exclusions, so it stops short of a 5.

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