what_changed

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations: it discloses the data source (purmemo-next ledger, which knows when a fact became true and when it stopped), result ordering (superseded facts newest-first), and the return structure (current-fact count, what replaced each, open contradictions, entity id). It also explicitly confirms 'Read-only,' consistent with 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?

The description is longer than average but well-organized into labeled sections (purpose, WHEN TO USE, EXAMPLES, Returns). The core purpose is front-loaded, and each section earns its place — the examples illustrate both parameters and the expected output format. Slightly verbose but structurally sound with no wasted sentences.

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 explain return values, and it does thoroughly: current-fact count, superseded facts with replacements, open contradictions, and entity id. It covers purpose, usage triggers, concrete examples, data source, and read-only nature. For a read-only query tool with rich annotations, this is complete — an agent has everything needed to call it correctly and interpret results.

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 100%, so both parameters (entity, limit) are already documented in the schema. The description adds example invocations showing realistic entity values ('purmemo-next', 'Mac mini', 'pūremail') and demonstrates limit usage, which is helpful but doesn't add meaningfully beyond what the schema already provides. The baseline of 3 is appropriate when the schema carries the documentation load.

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 purpose with a clear metaphor ('TIMELINE OF A THING') and precise scope: facts about an entity that were true and were replaced by newer facts, with dates and open contradictions. It names the data source (purmemo-next ledger) and explicitly distinguishes itself from plain search, which cannot answer this. The verb is implied but the tool's function is unmistakable.

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?

An explicit 'WHEN TO USE' section provides concrete trigger phrases ('what changed about X', 'what used to be true about X', 'when did X move/switch/get renamed', 'is this fact still current') and a use case (before relying on an older memory). However, it doesn't name a specific alternative sibling to prefer instead, only says 'plain search cannot answer this' — a vague exclusion rather than a named alternative.

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