journal

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

Annotations already cover readOnlyHint and openWorldHint, but the description adds real behavioral detail: secrets are redacted, values are capped at 4096 bytes and 65536 bytes overall, a cut appends [TRUNCATED] and sets truncated to true, and results are reduced to an allowlist. That is substantial data-handling context an agent cannot get from the annotations.

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 and read-only status are front-loaded, followed by a compact filter list and one dense paragraph on redaction and truncation. Every sentence carries information, though the truncation sentence packs several distinct facts into one run-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?

An output schema exists so return values need not be described, and the description still adds the truncated flag and allowlist behavior. The remaining gap is the undocumented required 'scope' parameter, which an agent must guess at.

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 load, and it documents six of seven parameters with concrete syntax examples for since/until ('2026-10-03 12:00' or '-1h') and priority ('err', 'warning..crit'). It omits any explanation of the required 'scope' parameter, which is the one the agent must supply.

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 the resource (journal entries), states the ordering (oldest first) and the projection (allowlist of fields), so an agent knows it is a log-read tool. The verb is only implied by the noun phrase plus 'Read-only', and nothing distinguishes it from siblings such as boots or unit_status.

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 filter list (unit, since, until, priority, grep, lines) implies how to narrow a query but never says when to choose this tool over boots or unit_status. There are no exclusions or prerequisites, so usage is inferred rather than stated.

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