diana_changes

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses genuinely useful behavior: the baseline is persisted on disk per project so edits from earlier sessions appear, AI-authored operations are hidden by default with their count still reported, model changes are truncated at twice max_operations, and peek controls whether the cursor advances. The one soft spot is that the default advance of the "last looked" point is a state write on a tool annotated readOnlyHint=true; this is bookkeeping rather than model mutation, so it does not rise to a contradiction, but it is left implicit.

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 opening line is front-loaded and the numbered Returns breakdown plus Args block map cleanly onto the two output streams and the six parameters. It is dense and the returns paragraph is long, but nearly every clause carries information; only the return-content enumeration is arguably redundant given an output schema exists.

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?

For a six-parameter polling tool this is close to complete: it explains baseline persistence, degraded no-bridge mode, and truncation limits. Since an output schema exists, the detailed returns description is a bonus rather than a gap; the only missing piece is failure behavior when no project is open or no baseline exists yet.

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 carry all six parameters, and it does: wait_seconds and quiet_seconds are defined together with their interaction ("how long the user must pause before returning (with wait_seconds)"), include_view and include_ai are scoped precisely, and max_operations explains the truncation rule including the doubling for model changes. This adds real semantics the bare schema titles do not provide.

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?

"What changed in DianaIE since you last looked" names a specific resource (change history) and the description spells out two concrete return streams: user operations since the last call and net model changes versus the last snapshot. It is clearly distinct from a simple diff or log tool, though it never names the sibling it supersedes (e.g. diana_model_diff or diana_command_log), so an agent must infer the boundary itself.

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 description implies a polling/changes workflow through wait_seconds/quiet_seconds and the persisted baseline, and notes the degraded mode ("without a bridge only the operations are available"). However it never states when an agent should call this instead of diana_model_diff, diana_command_log, or diana_model_snapshot, and gives no guidance on first-call behavior or recommended polling cadence.

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