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

With no annotations, the description carries the full burden and does well: it discloses the hard consent requirement, that approved_by/user_answer are persisted in schema history, that merges keep history while moving values, that omitted items are not re-offered, and that the data was already stored so this only organizes it. It does not cover failure/reversibility behavior on partial application, so not a full 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?

Long but well front-loaded: the consent precondition and the three core operations come first, followed by per-parameter semantics. Sentences are dense but each carries distinct information, with only minor redundancy between the opening list and the later parameter notes.

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 9-parameter, no-annotation mutation tool with an output schema (so return values need not be explained), the description covers purpose, gating, sequence, and per-parameter meaning adequately. A little more on partial-apply or rollback behavior would make it fully self-sufficient.

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%, so the description must compensate, and it defines the semantics of nearly every parameter: approved_by (who approved), user_answer (user's own words), descriptions/labels/merges shapes with examples, index, type_description, and items including its default behavior. Only proposal_id is left implicit (its meaning is obvious from the surrounding text).

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 specific verbs and resources: organize draft fields/values, register a new record type (type_...), or consolidate dictionary improvements into a dict_... type. It also names the relationship to the sibling propose_schema by casting itself as the applier of that proposal, letting an agent distinguish it without opening a 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?

Explicitly states when NOT to act ('Never call this on your own initiative') and the required sequence: show the propose_schema question, ask the user, call only after a yes. It names the alternative tool and the consent condition that gates use, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one meaningful trait — the returned state already reflects corrections/retractions — but says nothing about authentication, error behavior for unknown IDs, or read cost/rate limits.

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?

A single front-loaded fragment with no wasted words. It is efficient, though its brevity edges into under-specification rather than optimal concision.

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-value explanation is not required, and the tool is simple with one parameter. However, in a crowded sibling namespace the description omits any routing signal that would let an agent distinguish it from query or history, leaving a real contextual gap.

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 schema provides no explanation of entity_id. The description mentions 'one record' but never explains the identifier's form or origin, adding essentially no meaning beyond the parameter name.

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 fragment 'Current state of one record' communicates the resource but supplies no action verb and no sibling differentiation. With 13 siblings including query, history, and record, an agent cannot easily tell why it would call get_entity over those alternatives. Purpose is inferable but vague.

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?

No when-to-use, when-not-to-use, prerequisites, or alternative tools are stated. The parenthetical about corrections/retractions hints at timing but provides no selection guidance against siblings like query or history.

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

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

With no annotations, the description carries the full disclosure burden. It does add real behavioral value: completeness (ALL events, including corrections and retractions) and deterministic ordering by recording time. However, it says nothing about behavior when entity_id does not exist, or about result size limits for long-lived records.

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?

A single front-loaded sentence with no filler. The ordering guarantee and the inclusion of corrections/retractions are packed into the same clause that identifies the resource.

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 need not be explained, and a one-parameter read tool is simple. Still, the description omits the parameter's meaning and any failure behavior, leaving just enough gaps that an agent must infer how to call it correctly.

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 compensate, and it does not. 'One record' hints that a record must be identified, but entity_id is never named or explained, so an agent gets no confirmation that the parameter is the record identifier rather than, say, an event or series id.

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 makes the resource and return content concrete: 'Every event of one record, including corrections and retractions, in recording order.' This distinguishes it in substance from get_entity (current state) and query_log (query traffic), though it never explicitly names a sibling. The verb is implied rather than stated, keeping it short of a 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_entity for current state or query_log for other history types. The audit-trail purpose is inferable but never stated as a condition for selection.

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

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

With no annotations, the description carries the full burden. It usefully discloses the user-agreement gate, the draft-type side effect, and the returned batch_id, but says nothing about permissions (approved_by format), idempotency, or whether a second apply on the same preview is rejected.

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 verb and the gating constraint; the parenthetical and sibling pointer are compact. Every sentence earns its place, minor cost from the em-dash clause.

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-value detail is not required, yet the description leaves all three required parameters undefined on a mutation tool with zero annotations. The workflow gate is covered but the call contract is not.

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% and the description never explains preview_id, approved_by, or user_answer — including the free-form format of user_answer, which is the sort of value that will be guessed wrong. The description does not compensate for the schema gap.

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: write one preview as one ingest batch, and names the return value (batch_id). It implicitly distinguishes itself from ingest_preview/ingest_revert by the word 'apply', though it never names those siblings directly.

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 a hard precondition — ONLY after the user agreed to that preview — and routes the follow-up case (new entity types) to apply_schema_proposal. No explicit when-not guidance relative to ingest_preview or ingest_revert, but the gating condition is unusually clear.

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

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

With no annotations, the description carries the full burden and does so: it declares the tool writes nothing, discloses LLM cost (~one call per 15 chunks per stage), and explains internal behavior — evidence-checking that drops unevidenced values, merging of repeated facts, and conflict detection. This is unusually rich disclosure beyond a bare verb.

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 preview-only constraint and input options are front-loaded, and every clause carries information (return contents, cost, next step). It is dense and long, but no sentence is filler — slightly heavy for a single paragraph.

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 need not be re-explained; the description instead supplies exactly the missing context — safety (no writes), cost, input modes, and the handoff to ingest_apply. Nothing needed to call it correctly is absent apart from `source`.

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%, so the description must compensate. It covers text, path (file vs folder, .md/.txt), and exclude (skips file names), but never explains the `source` parameter (default 'text'), leaving one of four params undocumented.

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: turning mixed facts/rules/prose notes into records, with an explicit 'PREVIEW ONLY, nothing is written' scope. It clearly distinguishes itself from ingest_apply, which it names directly.

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?

Explicitly tells the agent how to supply input ('Give text, or path — a file or folder of .md/.txt files; exclude skips file names') and prescribes the workflow: show the user summary/ambiguous/conflicts, then call ingest_apply with their answer. The alternative tool and the condition selecting it are named, not inferred.

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

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

With no annotations, the description carries the full burden and does disclose the key mutation semantics: records are retracted but 'history kept', and series points are reverted — a meaningful reversibility/side-effect statement. It omits permissions required, whether the revert is itself undoable, and error behavior for an already-reverted or unknown batch.

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?

Two tight sentences, effect described first and the usage gate second, with no filler. Every clause adds information.

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?

Complexity is low (one parameter) and an output schema exists, so return values need no explanation. The effect, reversibility nuance, and usage gate are covered; only permissions and failure modes are missing for a destructive operation.

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?

One required parameter (batch_id) with 0% schema description coverage, so the schema contributes nothing. The description implies the batch is the unit of operation ('one ingest batch') but never explains where batch_id comes from or its format; baseline 3 for a self-evident identifier the description only implicitly covers.

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 verb and resource ('Undo one ingest batch') and immediately names the concrete effects: records retracted, series points reverted. It is clear what the tool does, though it never distinguishes itself from the near-identical sibling revert_series_batch, so the agent must guess which scope applies.

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?

'Only when the user asks' is an explicit, unusually strong usage gate that tells the agent this is a user-initiated, not autonomous, action. It stops short of naming alternatives (ingest_apply, ingest_preview, revert_series_batch) or when-not conditions beyond that single gate.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses non-obvious content traits (unregistered fields/values already in use, approval history), but it says nothing about read-only nature, scope, filtering behavior, pagination, or permissions.

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?

A single dense sentence with no filler, front-loaded on the primary content (record types and fields). It is slightly run-on when enumerating drafts and approval history, but nothing is wasted.

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?

Because an output schema exists, return values need not be spelled out, yet the description reasonably previews the payload shape. However, for a tool whose only input is undocumented, the definition is not complete enough to call confidently without opening the schema.

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?

The single parameter 'name' has 0% schema description coverage and is never mentioned in the description, so its purpose (presumably filtering by record type) is unexplained. The description does not compensate for the coverage gap, leaving the only input ambiguous.

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 names a specific resource — record types (schemas) — and enumerates what comes back: fields, descriptions, allowed values, drafts, and organize-approval history. An agent can tell this is a read of schema definitions, but it never states an explicit verb and offers no differentiation from nearby tools like propose_schema or apply_schema_proposal.

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?

There is no statement of when to call this versus alternatives such as propose_schema, apply_schema_proposal, or query. The description only characterizes the payload, leaving the agent to infer that this is the inspection counterpart to the proposal tools.

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

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

With no annotations, the description carries the full burden and does fairly well: it signals the operation is non-destructive ('never applied automatically'), clarifies that the fields/enums already exist and are 'stored and queryable' so nothing is lost, and explains what organizing actually does (adds descriptions, labels, indexes, merges look-alike names). It does not mention permissions or rate limits, but the safety-relevant behavior is well disclosed.

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 key constraint ('never applied automatically') is front-loaded, followed by the two modes in parallel structure. It is dense but every sentence contributes; the phrasing 'how to organize drafts' is slightly loose but does not waste space.

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 need not be explained. For a two-parameter, fully optional proposal tool, the description covers both invocation modes, the non-persistent nature, and the handoff to apply_schema_proposal, leaving little an agent would need to infer.

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 neither parameter has an inline description, so the description must compensate. It does: 'samples' is tied to the 'with samples and a new entity_type' mode and 'entity_type' is named as the key for a new record kind, giving each parameter a distinct role rather than leaving them opaque.

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 (propose) and resource (schema), and immediately distinguishes itself from the sibling apply_schema_proposal with '(never applied automatically)'. It also spells out the two operating modes (organize existing unregistered fields vs. draft a schema for a new entity_type), so an agent can tell what it will produce.

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 a clear mode-selection rule: 'Without samples' = organize drafts, 'With samples and a new entity_type' = first draft for a new record kind. It also routes correctly by instructing 'Ask the user before apply_schema_proposal.' It lacks an explicit 'when NOT to use' beyond this handoff, but the context is clear.

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

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

With no annotations, the description carries the full burden, and it does disclose the destruction scope (entries before the timestamp, or everything when omitted) and a confirmation requirement ('Only when the user asks for it'). It also bounds the blast radius ('Recorded facts are not touched'). It stops short of stating irreversibility or any permission requirements.

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?

Two short sentences, front-loaded with the action and parameter semantics, followed by the safety constraint and scope boundary. No filler; every clause contributes.

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 need no explanation, and the single parameter plus the no-argument case are both covered. The remaining gap for a destructive, annotation-free tool is whether the purge is recoverable, which the description does not address.

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% — the schema only says `before` is a nullable string defaulting to null. The description compensates by naming the ISO 8601 format and, importantly, the default semantics: omitting it deletes all entries. That is meaning the schema does not convey.

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 (delete query log entries) plus the scoping rule (before `before`, or all when omitted). It implicitly separates itself from the data-recording siblings by noting 'Recorded facts are not touched', though it never names `query_log` or another alternative directly.

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?

'Only when the user asks for it' gives a clear consent guardrail, which is real usage guidance for a destructive tool. However, it does not say when to prefer this over `query_log` inspection, `history`, or a revert path, so routing between siblings is left to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does add genuine value beyond structured fields: narrate's LLM 'only sees aggregates', spec means 'no LLM is used', and 'by' is persisted in the local query log. It stops short of stating read-only scope, auth, error behavior, or what 'evidence' actually contains.

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 a one-line purpose, followed by a compact per-parameter list with no filler. Slightly dense formatting (inline indented param notes) but every line 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?

An output schema exists, so return values are covered and need not be explained. With no annotations, the description should carry the behavioral and routing load, but it omits sibling differentiation and the QuerySpec structure, leaving meaningful gaps for a 4-parameter tool.

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 compensate; it does explain question, narrate, and by meaningfully (though 'by' restates the schema default). The critical 'spec' parameter is only described as 'optional structured QuerySpec' with no shape or pointer to list_schemas, leaving the agent unable to construct it.

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 recognizable action ('Answer a question') against a resource ('the record book') and flags that evidence is returned. However, 'record book' is undefined domain jargon, and the definition never distinguishes this from siblings like query_log, history, or get_entity, so an agent cannot cleanly route between them.

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?

There is no explicit when-to-use/when-not-to-use guidance relative to query_log, history, or get_entity. The only implied usage signal is the spec conditional (structured spec bypasses the LLM), which is a behavioral note rather than routing guidance.

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

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

No annotations are provided, so the description carries the burden. It clearly signals a read/inspection operation by describing the logged fields returned, but never states the operation is read-only, what access it requires, or any retention/limit constraints. Adequate but not rich for a no-annotation tool.

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 purpose line is front-loaded, which is good, but the `view` block packs heavily nested parentheticals (e.g. 'empty ... with `path`, e.g. cache, only those') that require re-reading. Content mostly earns its place, but the structure is cramped.

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 need not be explained (the field list is mildly redundant), and parameter meaning is well covered. The remaining gap is sibling disambiguation versus `history`/`purge_query_log` and an explicit read-only statement.

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 compensate, and it largely does: it enumerates `view` modes, gives the enum-like values for `path` (fast | cache | llm | structured | entity | none), defines `since` as ISO 8601, and conveys `n` via 'recent (last n)'. Only the interaction between views and `path` is described densely rather than fully.

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 (earlier questions / the query log) and enumerates the fields returned (interpretation, QuerySpec, SQL, result count, evidence ids, warnings, tokens, cost), so an agent can tell it inspects past query records. It stops short of differentiating itself from the sibling `history`, which likely covers overlapping ground.

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?

Each `view` value carries context on when to pick it (e.g. `empty` = 'answers that found nothing — check whether the reading was wrong', `diverging` = 'the same question pattern answered with different SQL'). This gives real selection guidance, but no explicit when-not or named alternative tool.

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

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

With no annotations, the description carries the full burden and does so well: it enumerates all four status outcomes (recorded/clarify/rejected/error) and states precisely what is and isn't stored in each, plus side effects like drafts, questions, and proposals. That is exactly the mutation/side-effect disclosure an agent needs before calling.

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 content is dense and each block (modes, drafting, status codes) earns its place, and the core purpose is front-loaded. The formatting is somewhat run-on and the nested parentheticals make it harder to scan than it needs to be.

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 12-parameter tool with zero schema descriptions and no annotations, this is about as complete as a description can be: input modes, edge cases, draft/proposal workflow, and the full status taxonomy are all covered. The output schema exists, so return-shape detail is appropriately not duplicated.

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 compensate, and it does: it documents entity_type, kind (with its five enum values), payload, entity_id, match (with an example), text, at (ISO 8601 with offset), at_precision (time|date|unknown), by, evidence, new_type, and even the schema_draft shape. Nearly every one of the 12 parameters gains meaning absent from 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?

The opening 'Record a fact. Either structured or free text.' states a specific verb and resource, and the two modes are laid out precisely. It references siblings (list_schemas, apply_schema_proposal) but never contrasts itself with record_series, the closest sibling, so the differentiation is good but not complete.

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?

Strong conditional guidance: structured vs free-text input, when to send schema_draft, when the reply produces a proposal, and to call apply_schema_proposal on user confirmation. It also tells the agent to ask the user and re-call on 'clarify'. What's missing is any explicit when-not-to-use or alternative-tool routing.

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

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

With no annotations the description carries the full burden and does well: it discloses transactional atomicity ('all or nothing', `rejected` reason on failure), upsert semantics for duplicate key+time including that previous values are kept for the batch, the meaning of the by/source provenance fields, and the batch_id/counts response with a reversal route. Gaps are permissions/auth requirements and any rate or size limits on a batch.

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 verb and resource, then a worked example, then the batch semantics and return/undo behavior — minimal waste. The parenthetical around the example is slightly dense, but every sentence adds operative information.

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 four-parameter mutation tool with no annotations, the description covers the essentials: point shape, atomicity, upsert behavior, provenance fields, and the undo sibling. Since an output schema exists it need not restate return values, yet it still names batch_id and counts. Only authorization expectations are left unaddressed.

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 every property is a bare title, so the description must compensate — and it does, defining `entity_type` via the series-type concept, `by` as the agent name, `source` as the value's origin (file, app, "user said"), and `points` through a concrete example showing key field, time field and measure. This effectively documents all four required parameters.

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 — record measurements over time for a 'series' type — and even defines what a series type is by pointing at list_schemas for its key fields, time field and measures. It is clearly distinct from the plain 'record' sibling in framing, though it never contrasts them explicitly.

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 a clear context of use (time-series measurements keyed by a series type) plus the prerequisite discovery step via list_schemas, and names revert_series_batch as the undo path. No explicit when-not-use condition or comparison against the 'record' sibling is offered.

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

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

With no annotations, the description carries the full burden and does well: it discloses the destructive effect (new points removed), the restorative effect (updated points get previous values), and a refusal condition dependent on batch ordering. It omits permissions/auth requirements and whether the revert itself can be undone, which keeps it from 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?

Three short sentences, front-loaded with the core action, then the failure condition, then the usage gate. Every sentence carries distinct information with no filler.

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 single-parameter mutation with an output schema (so return values need no explanation), the description covers effects, preconditions, and invocation policy. The main remaining gap is that `batch_id` provenance is never established, which matters for a tool whose whole input is that opaque id.

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?

There is a single required parameter, `batch_id`, with 0% schema description coverage, and the description adds nothing about it — no format, no source (e.g., from a prior record_series call), no scope. The schema alone leaves the agent guessing what a valid batch id looks like.

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 uses a specific verb ("Undo") plus resource ("a whole series batch") and then defines exactly what that means: new points removed, updated points restored to prior values. That is far more precise than a bare 'revert'. It does not, however, distinguish itself from the nearby sibling `ingest_revert`, which an agent could reasonably confuse with this tool.

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 an explicit when-to-use gate ("Only when the user asks") and a concrete precondition/refusal rule — if a later batch touched the same points the call is refused and you must revert that one first — which effectively points to an alternative action. It stops short of naming sibling tools or other alternatives, so there is no explicit tool-routing guidance.

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