diana_command_log

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

The readOnlyHint and openWorldHint=false annotations already declare the safety profile, but the description goes further: it explains the attribution source precedence ('unknown = no bridge journal'), that undone steps are marked, that redo/undo entries record what they reverted, and the default session resolution order (bridge's, else running, else newest). The only gap is that it does not say how the `list_sessions` mode changes the response shape, which is the most surprising behavior for an agent to trip over.

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?

The headline sentence is front-loaded and the routing rule follows immediately, then the Args block. It is longer than most definitions, and the inline parentheticals (user = GUI or command console, ai = this server's bridge, unknown = no bridge journal) make the opening sentence dense, but every clause carries information an agent needs.

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-shape detail is not required, and everything else is present: all six parameters are explained, the default session fallback chain is specified, permissions are covered by annotations, and the alternative tool is named. Nothing an agent needs to call this correctly is missing.

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 carries the full burden, and the Args block documents all six parameters with meaning beyond the schema: lines 'counted from the end', find 'case-insensitive' over call or description, session accepting either a history file path or an IEhistory_yymmdd_hhmmss key, edits_only excluding views/plots/queries/reports, source restricting to user or AI commands, and list_sessions acting as a listing mode instead of a log read.

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 states a specific resource and its scope: 'every command of a DianaIE session, GUI clicks included, as the exact Python call with a plain-language description,' and adds the attribution model (user/ai/unknown). It also explicitly separates itself from the sibling diana_changes, so an agent can distinguish the two without opening either 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?

It gives two concrete routing rules: use it to learn the exact call behind a GUI action ('ask the user to do it once and read it here') and use diana_changes for 'what did the user change since I last looked'. It also states the tool works without a bridge and on earlier sessions, which removes the main precondition an agent would otherwise have to guess.

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