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

Annotations already declare readOnlyHint=true, and the description adds real behavioral context beyond that: the return ordering ('most recently updated first'), the incremental-sync behavior of sinceVersion, and the cursor-based pagination with 'pass next'. It does not mention result caps or rate limits, which keeps it short of 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?

Purpose is front-loaded in the first clause, followed by the return shape, then parameter usage in a compact semicolon-separated sequence. It is a single long sentence with no wasted filler, though the density borders on run-on.

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 read-only listing tool with no output schema, the description supplies the returned field shape, sort order, pagination protocol, and incremental-sync mechanism, which covers what an agent needs to call and interpret it. Missing only edge behavior such as empty-result or stale-cursor handling.

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 carries the full burden and mostly delivers: sinceVersion is explained as 'the version you cached', state as a filter with 'open'/'closed' examples, and limit/cursor as the pagination pair with 'pass next' describing how to advance. Only limit's exact semantics (max page size) are left implicit.

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 the resource ('every Event') and its scope ('in brief', 'most recently updated first') plus the inline shape {id, title?, state, parents, progress?, updatedAt}, so an agent knows this is a bulk directory listing rather than a search or a single-record get. It does not name a sibling tool explicitly, but the scope is distinct enough from event_search and event_get_protocol to be usable.

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?

'From which you decide what to read' implies the intended workflow (list first, fetch details later) and sinceVersion is framed as the change-detection path. However, there is no explicit when-to-use-this-vs-event_search guidance and no stated preconditions, so usage is implied rather than directed.

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?

Annotations only say readOnlyHint=false and destructiveHint=false, which the description is consistent with. The description adds substantial behavioral context beyond that: the verbatim rule for text/accountText, the at-most-one owner constraint, statement length bounds, absolute-date requirement, inference/basis marking, and the return shape. It does not cover error/idempotency behavior, keeping it just short of the top band.

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 purpose, then constraints, with no filler sentences. The dense semicolon-chained phrasing is information-rich but slightly harder to scan than a cleanly separated list of rules.

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, nested-object tool with no output schema, the description supplies the return shape ({entityId, version, accountId, added}) and covers the highest-risk fields (text, accountText, owner, statements). Parameters like via, aliases and accountSource are left to the 89% schema coverage, which is acceptable but leaves minor gaps.

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 already 89%, so the baseline is 3, but the description adds real meaning: it clarifies the verbatim rule (trimmed, never summarized, only the part about this Entity), tightens owner to 'at most one', and explains that statements are the agent's one-fact interpretation with basis for inferences. This goes beyond the schema text rather than repeating 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?

States a specific verb (Create) and resource (an Entity), then defines the resource precisely as 'one specific person, animal, thing or place that recurs across Events or applications.' It also distinguishes the tool from the alternative modeling choice (a criteria ref on the Event), so an agent can tell what this tool is for 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?

Explicitly routes the agent: 'Search first (entity_search)' names the sibling to check before creating, and 'otherwise use a {criteria} ref on the Event' states the condition under which this tool is NOT the right choice. Both when-to-use and the alternative path are present.

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 readOnlyHint=true already declaring safety, the description still adds meaningful behavior: summary excludes sensitive Statements by design, full returns non-outdated Statements ordered by topic then creation, and includeHistory/includeEvents modify the payload. It does not discuss permissions or error behavior, so it falls short of exhaustive.

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?

One dense paragraph, front-loaded with the core action before parameter detail, and every clause carries information. It is slightly run-on with stacked parentheticals, but there is 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?

There is no output schema, so the description rightly explains return shape per view and per modifier, including ordering and the sensitive-data exclusion. For a single-required-parameter read tool with readOnlyHint, nothing material is missing.

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 only 20% (entityId alone), so the description must carry the load, and it does: it defines entityId (id or "current_user"), the two view values and their distinct return shapes, and what includeHistory, includeEvents, and topics each add. Every parameter gains meaning beyond the bare 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?

"Read one Entity" gives a specific verb and singular resource, which implicitly separates it from the sibling entity_search and entity_create. However, it never names an alternative explicitly, so the differentiation is inferred rather than stated.

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 clear context for choosing view: "summary" is framed as the short list "meant to be loaded into every conversation (never sensitive ones)", while "full" is the default. That is real when-to-use guidance for parameters, but there is no guidance on when to reach for entity_get versus entity_search.

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?

Beyond the annotations (readOnly=false, destructive=false), the description discloses real behavior: duplicate words are merged into the existing Statement as further evidence, USER_WORDS_PROTECTED and USER_CONFIRMATION_REQUIRED constrain what can be superseded or restored, and expectedVersion is an optimistic-concurrency token. With no output schema, it also spells out the return shape {entityId, version, accountId, added?, merged?, changed?, supported?}.

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?

It is one dense paragraph with no structure, and several clauses restate what the schema already says (aliases as the complete list, update fields, sensitivity behavior). The purpose is front-loaded correctly and most sentences carry non-obvious rules, but the wall of text makes the protected-statement and versioning rules easy to miss.

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 11-parameter nested write tool with no output schema, the description covers the important ground: merge semantics, protection rules, concurrency, verbatim requirements, and the response shape. Gaps remain around when to prefer sibling recording tools and around parameters like name and via, but nothing critical for a correct call is missing.

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 73%, and the description adds genuine meaning on top: aliases is the complete replacement list, add can supersede or conflict and carries a basis for inference, update covers status/reason/sensitivity/inSummary, and expectedVersion must come from the last read or write. It also states the verbatim rule for text. One flaw: it refers to 'accountText', which does not exist in the schema (the field is accountSource), and name and via get no semantic help.

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 sentence states a specific verb and resource: record the user's words about an Entity together with the changes they make (name, aliases, add, update, support). This is a precise write operation, and the required entityId plus versioning makes it implicitly distinguishable from entity_create. It never names a sibling tool explicitly, so differentiation from event_note or entity_create is left to inference.

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 situational guidance for the protected-statement case (add your version with conflictsWith instead of superseding the user's words) and for disputed statements (USER_CONFIRMATION_REQUIRED). However, it never states when to call this versus entity_create, event_note, or event_record_expression, and there are no explicit exclusions. Usage is implied by the parameter contract rather than stated.

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 only readOnlyHint=true in annotations, the description carries the behavioral load and does: it discloses the result ranking tiers (exact name/alias match, then prefix/contains, then statement matches, case-insensitive), the no-query listing default, and the returned card contract including that 'statements' counts only non-outdated statements. That is substantial disclosure beyond 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?

Purpose is front-loaded in the first clause, followed by ranking, default scope, and return shape in a single dense block with no filler sentences. The length is justified because there is no output schema to absorb the return contract.

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 read-only, zero-required-parameter search with no output schema, the description covers ranking, default scope, and return fields well enough to call correctly. It stops short of documenting the limit/pagination behavior, so it is not fully complete.

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 67%; kind and query are documented in-schema, and the description adds semantics the schema cannot express, namely that omitting query lists everything and that match ordering depends on the query. The limit parameter is left unexplained in both places, which keeps this from a 5.

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?

Names a specific verb and resource ('Find the people, animals, things and places ... (Entities)') and frames the resource in domain terms an agent can map to the sibling entity_create/entity_get. The dedupe rationale ('so that one does not become two') makes its role relative to entity_create 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?

Gives a concrete when-to-use trigger ('before creating one') and states what happens when the query is omitted versus supplied. It does not explicitly name the alternative (entity_get for direct ID lookup), so an agent must infer the boundary, but the usage 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 annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context: idempotency ('Adding an existing link changes nothing'), a specific failure mode ('a link that would close a cycle fails with PART_OF_CYCLE'), and the returned shape. These are exactly the mutation semantics annotations cannot convey.

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?

Four dense sentences, front-loaded with the core action, then the usage rule, then behavior, then return value. Every clause carries information an agent needs to call the tool correctly.

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 mutation tool with no output schema, the description supplies the return shape, the idempotency rule, the cycle error, and the grounding requirement. Combined with 100% schema coverage and annotations, nothing critical is missing for correct invocation.

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 the baseline is 3. The description restates the grounding constraint for sourceAccountIds ('Ground the link on Accounts of the child or of the parent') but adds no syntax or format detail beyond the schema, and expectedVersion semantics are left entirely 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 ('Link an Event (child) as part of a larger Event (parent)'), making the relationship direction and scope unambiguous. An agent can distinguish this from the inverse sibling event_remove_parent without opening either 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 gives both the positive condition ('plainly part of it or a step toward it') and the negative exclusion ('two separate trips are siblings'). It also states the grounding requirement on Accounts, leaving little to inference about when a link is appropriate.

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?

Annotations only declare readOnlyHint=true, so safety is covered; the description goes further by disclosing non-obvious behavior: accounts default to 20 (or 'all'), ordered oldest first, and Entities are returned only 'when its refs name Entities'. These conditional and defaulting behaviors are exactly the kind of context annotations cannot convey.

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 that front-loads the primary return shape before the conditional Entity detail and the sibling routing. Nothing is wasted, though the packing of return-shape, defaults, ordering, and routing into one sentence makes it slightly hard to scan.

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 carries the return-value burden and does so by specifying the payload shape, the Accounts default/ordering, and the Entity object shape. Error behavior and pagination details are not covered, but for this tool the coverage is close to complete.

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 50%: eventId is documented, but the accounts parameter has no schema description. The tool description compensates by explaining the default (20) and the 'all' sentinel value, plus the ordering semantics, which is real added meaning beyond 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 ('Read one Event') and enumerates the exact return payload ({event, accounts, entities?}), so an agent knows precisely what comes back. It also explicitly separates itself from event_get_revisions, naming the sibling that handles history.

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 closing clause 'History is read with event_get_revisions' routes the agent to the correct alternative for the adjacent use case, which is genuinely useful guidance. It stops short of a full when/when-not statement for the other siblings, but the key disambiguation is present.

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?

The readOnlyHint annotation already covers the safety profile, and the description goes further by disclosing entries are returned in commit order and that paging is cursor-based via 'pass next', which hints at a next-cursor in the response. It stops short of describing the response payload or default page size.

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 core purpose and followed by pagination mechanics. No filler or redundancy.

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 simple read-only tool with no output schema and only three parameters, the description covers purpose, ordering, and pagination adequately. Minor gaps (default limit, cursor expiration) remain but are not blockers for correct invocation.

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 only 33%, with 'after' and 'limit' undocumented in the schema, so the description must carry them. It does clarify their role: 'limit' sets page size and 'after' carries the cursor ('pass next'), adding real meaning beyond the bare string/integer types.

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+resource: reading an Event's revision history in commit order. A sibling like event_undo_revision is distinguishable by its mutating name, though the description never explicitly contrasts itself with siblings.

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 by the subject matter (inspect past versions), and pagination mechanics are given. However there is no guidance on when to prefer this over siblings such as event_get_protocol or event_search, and no stated prerequisites or exclusions.

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?

Annotations only declare this is a non-read-only, non-destructive write, so the description carries most of the weight and does so well: it scopes the side effect ('Changes nothing else (it gives a title only to an Event that has none)'), names the resulting state ('emerging'), and notes it 'Returns a receipt.' It does not mention permissions, idempotency, or whether appended words can be removed, which keeps it short of 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 core action and mode split, then constraints, then the verbatim rule. Despite several sentences, every one carries a rule the agent must obey (title scoping, directory check, no paraphrase, split multi-Event messages), with no filler or restatement of the name.

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 7-parameter mutation with a nested actor object and no output schema, the description covers the important behaviors and does state the return shape ('a receipt') at a high level. Not explaining receipt fields is acceptable, though actor/accountSource semantics are only in the schema, not elaborated here.

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 the baseline is 3, but the description adds cross-parameter conditional semantics the schema states only piecemeal: eventId presence selects append-vs-create, title applies only to new or untitled Events, and parentEventId applies only to a new Event. The verbatim constraint on text is also reinforced beyond the schema's single-line note.

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 the user's words on an Event, or start a new Event with them') and covers both operating modes. It only hints at sibling separation via 'Interpretation belongs in the fields,' never naming event_record_expression or the other event_* tools, so differentiation is inferential rather than explicit.

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 explicit branch conditions: 'With eventId the words are appended; without it a new Event starts in state emerging, optionally titled and placed under parentEventId.' It also adds a precondition ('Check the directory first so one matter does not become two') and routes interpretation elsewhere, leaving little to infer.

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?

Annotations already declare a non-read-only, non-destructive write, and the description adds genuinely important behavior beyond them: replacement semantics ('each supplied field replaces the stored one, supply its complete current content'), null-removes-a-field, atomicity, and that a receipt is returned. Version-conflict handling is left to the schema rather than the description, which keeps this 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?

One dense paragraph, front-loaded with the atomic record-and-set purpose, followed by the fold-into-fields path, replacement semantics, and the verbatim rule. Every sentence carries an instruction; it is long but not padded, though the verbatim rule could be tightened.

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 8-parameter write with nested objects and no output schema, the description covers atomicity, replacement/removal semantics, the Account-grounding path, and that a receipt is returned. The receipt's contents are only implied, and conflict recovery is delegated to the schema, but nothing essential to calling it correctly is missing.

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 the structured fields carry most of the load and the baseline is 3. The description earns above baseline by explaining the non-obvious accountId + exact-text pattern and by restating the verbatim contract for text, both of which are workflow semantics the schema does not fully 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?

Names a specific verb and resource: recording the user's words together with the field changes they support, atomically, and enumerates the settable fields (title, state, progress, facts, refs, metadata). It is clear what the tool does, though it never distinguishes itself from close siblings such as event_note or event_record.

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 one concrete usage rule: to fold earlier-recorded words into fields, pass accountId with that exact text rather than new words. That is useful, but there is no guidance on when to choose this tool over the sibling write tools (event_note, event_record), nor any when-not-to-use statement.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered; the description adds genuine value by disclosing the failure mode (NOT_FOUND for a missing link) and the return payload {eventId, version, parents}, which no output schema supplies. It omits permission/auth requirements and whether expectedVersion mismatch is an error.

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 with no filler, front-loaded with the action and the link's meaning, then failure behavior, then return shape. Every sentence carries distinct 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 destructive mutation with no output schema, the description covers the action, the grounding requirement, the failure case, and the return shape, which is enough to invoke it correctly. Gaps are minor: it does not address version-conflict handling or authorization, and nested actor semantics are left to 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds semantic framing beyond the schema: 'grounded on Accounts of the child or of the parent' explains the rationale for sourceAccountIds, and 'child is part of parent' disambiguates the direction of childEventId vs parentEventId. The expectedVersion parameter's concurrency behavior is still only explained by 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?

Specific verb plus resource: it removes the 'child is part of parent' link and defines that relation precisely, which is clearer than a bare 'remove parent'. It contrasts implicitly with the sibling event_add_parent through the verb, but it never names a sibling or explicitly says how it differs from other event_* tools.

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?

Implies usage through operational detail: the link must rest on an Account of the child or parent, and calling it on a non-existent link fails with NOT_FOUND. However, it gives no explicit when-to-use guidance or routing to alternatives (e.g. event_add_parent, event_note, event_undo_revision), leaving the agent to infer the scenario.

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?

Annotations only declare readOnlyHint=true, so the description carries most of the burden and does well: it discloses that matching is lexical, not semantic, spells out the three-tier ranking order, and states results come 'in brief' with best matches first. It stops short of covering limits on result count or pagination behavior.

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?

Dense and front-loaded, with the purpose and the create-avoidance rationale first, then matching semantics, then the two filters. The middle sentence is a long run-on, but every clause (rounding, ranking, return shape) carries information the agent needs, so nothing is padding.

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 3-param, read-only search with no output schema, the description covers the essentials: required query, both optional filters, ranking order, and a rough return shape ('{events} in brief'). Missing only edge details like default limit and whether results are paginated.

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 only 33% (query is documented, limit and state are not), so the description must compensate, and it largely does: it explains state as 'a state, "open" or "closed"' (clarifying the enum grouping) and that limit 'caps the number returned'. It omits default limit and the meaning of the individual states, leaving some 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?

The description states a specific verb and resource ('Find Events for a query') and immediately frames the scope in a way an agent can distinguish from entity_search or event_get: it searches Events by text. The parenthetical use case ('before creating one') makes the role of the tool 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?

It gives a clear when-to-use condition ('before creating one, so one matter does not become two'), which is exactly the decision point an agent faces. It does not, however, name an alternative tool or an exclusion (e.g., when to prefer entity_search or event_get instead), so it falls short of the 5 rubric.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond that: events and words are never removed, the REVISION_NOT_REVERSIBLE failure mode including the concurrent-writer case, and the fact that the call itself records a revision.reverted Revision. This is unusually rich behavioral disclosure.

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?

Dense single paragraph, but front-loaded with the action and every clause carries information (scope, exclusions, error, side effect, iteration). Slightly overpacked for a quick read, hence not a 5.

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?

No output schema exists, yet the description explains the return (the recorded revision.reverted Revision), the preconditions, the failure code, and the retry/walk-back pattern. Nothing essential for correct invocation is left implicit.

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% and the actor field carries a detailed description in the schema, so the baseline is 3. The description only loosely ties revisionId to the change being undone and adds no format or sourcing detail beyond what the schema already states ('from event_get_revisions').

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 precise verb+resource (undo the latest change of an Event) and immediately narrows scope to the reversible revision kinds (field.changed, parent.added, parent.removed), which distinguishes it from siblings like event_get_revisions and event_add_parent. An agent can tell exactly what this does 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?

Explicitly says when it applies (latest not-yet-undone reversible change), when it does not (event.created, account.added, an undo, or anything else), and what to do on failure (read the Event again and reconsider). It also explains how to walk further back by calling again on the next change.

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 readOnlyHint already declaring safety, the description still adds substantial behavioral context: the checkpoint/remaining pagination contract, the batch-boundary invariant ('a batch never ends between two Accounts with the same createdAt'), and the idempotency guarantee from complete field writes. This goes well beyond what the annotation provides.

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?

Purpose is front-loaded, followed by return shape and then operational guidance, and no sentence is filler — the return enumeration, boundary invariant, and idempotency note all earn their place. It is a dense unbroken paragraph rather than being over-long.

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?

There is no output schema, so the description carries the full return-shape burden and does so explicitly ({version, checkpoint, remaining, events} plus per-Event field list). Combined with pagination semantics, idempotency, and both parameters, an agent has everything needed to call and loop this tool 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: 'since' can be a previous checkpoint or an early time to read everything, and 'limit' interacts with the batch invariant rather than being a naive row cap. That is more than the schema's terse 'number of Events per batch.'

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+resource: retrieving the words recorded since a moment, framed for incremental folding into fields or cache refresh. It is clearly a delta/sync read, distinct in spirit from event_search and event_get_revisions. It does not, however, explicitly name an alternative sibling, so it falls short of full differentiation.

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 a concrete usage pattern: 'Pass checkpoint as the next since to continue; remaining counts the Accounts not yet returned,' which tells the agent how to drive the pagination loop. It also says reading the same words twice is harmless. It stops short of saying when to prefer this over event_search or context_pack.

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