import_records

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

Annotations only declare the generic profile (write, idempotent, non-destructive), so the description carries real weight: it discloses that newer snapshots replace current state while prior versions are retained in history, that the write is atomic, and that observation times are validated. It stops short of describing failure behavior (e.g., whether one invalid observation time rejects the whole batch) or any permission requirements, which for an atomic batch import would be useful.

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?

Three tight sentences, front-loaded with the action, followed by the caller-critical completeness rule and then the storage semantics. Every clause carries information; the closing telegraphic triplet 'Atomic, versioned, validates observation times' is dense but earns its place.

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 an atomic batch write over a five-variant union with no output schema and negligible annotation detail, the description covers replacement, versioning, atomicity and validation but omits what the caller gets back (version identifiers, per-record outcomes) and the batch limits. It is adequate to call the tool but leaves the agent guessing about result handling and failure modes.

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% and there is a single, deeply unioned 'records' parameter with five record kinds and nested item/event/message arrays. The description compensates partially by clarifying that arrays must be complete and that observedAt is validated, but it never enumerates the kind variants (order/shipment/transaction/chat/product) or the batch size ceiling, leaving most of the union's semantics to the schema.

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 specific verb and resource — 'Import complete entity snapshots into the local database' — so the agent knows this writes full-state records rather than fetching them. It does not differentiate from the closest sibling, record_history, which is the natural counterpart for reading the versions this tool preserves.

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?

Usage is implied rather than stated: 'Include the complete messages/events arrays' and 'a newer snapshot replaces the current one' tell the caller this is a full-snapshot push, not a delta append. There is no explicit when-to-use/when-not guidance and no pointer to record_history for reading prior versions, so the agent must infer routing.

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