history_diff

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

With no annotations, the description carries the burden well: it discloses retention limits ('still retained'), the sampling caveat that a stored position is a sample widened by window_sec, and critically the 'recorded: false' semantics warning that an empty archive is not a quiet period. It omits whether the call is read-only and any permission/cost constraints, which keeps it just under a 5.

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?

Front-loaded with the operation, then the data-source caveat, then parameter notes, then the failure-mode warning – a sensible ordering with no filler sentences. Slightly verbose phrasing ('a stored position is a sample rather than a continuous truth') costs a point but earns its place as a real caveat.

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 needn't be explained, and the recorded:false note is a strong addition. But for an 8-parameter, 5-required tool with zero schema coverage and no annotations, leaving the bbox corners and 'kind' undefined is a real completeness gap an agent cannot resolve from structured fields alone.

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% – every parameter is a bare title – so the description must compensate and only partly does. It explains at_a/at_b as epoch seconds with at_b defaulting to now and explains window_sec's widening purpose, but lamin/lomin/lamax/lomax are only gestured at by the word 'box' and the 'kind' parameter is never mentioned at all.

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 concrete operation on a concrete resource: a spatial/temporal diff ('what changed inside a box between two moments') returning arrived/departed/stayed. The scope (bounding box + two timestamps) is distinctive enough that an agent can separate it from general siblings like whats_changed or track_history without opening the 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?

Gives clear context for when to reach for it: it answers from OWNED/retained history for any past window 'rather than only the present instant', implicitly routing present-state questions to siblings like get_situation. It stops short of naming a specific alternative or stating exclusions, so it is clear context without explicit routing.

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