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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It warns that missing and non-numeric values are skipped rather than zeroed, explains double-counting in linked grouping, states group ordering, and points to groups_truncated for overflow. These are exactly the caveats an agent needs before quoting results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence adds operational value. Compact notation for metrics and group_by, a concrete example, and a highlighted ALWAYS warning make the complexity manageable without wasted words.

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?

Given 8 parameters, no annotations, and an output schema that can define return fields, the description covers the main call patterns, edge cases, and result caveats. Minor gaps such as the role of limit and full self-contained filter semantics keep it from being fully complete, but it is strong overall.

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 compensates by precisely specifying metrics and group_by syntax and referencing search_records for filter parameters. It leaves limit and the full details of where/filters/text/linked_to implicit, but the core aggregation parameters are documented well enough for correct invocation.

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 opens with a specific verb and resource ('Count and total active records on the server') and immediately contrasts with manual paging, making it clear this is the aggregation counterpart to search_records. It is not a tautology and clearly differentiates the tool from sibling read/fetch 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?

The phrase 'instead of paging and adding by hand' gives a strong when-to-use signal, and 'Filters are the same as search_records' routes the agent to a familiar sibling. However, it does not explicitly state when not to use aggregate or how to choose among all read-focused siblings.

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 behavioral burden, and it does so well: it discloses the REVIEW_REQUIRED return, the soft-delete behavior, version increment, retention of audit history and links, and exclusion from ordinary search. This prevents an agent from assuming a hard delete or a standard write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three compact sentences with no filler. The legacy warning and alternative is front-loaded, followed by side effects and search visibility, so every sentence 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 a two-parameter tool with an output schema, the description covers the return state, side effects, and search visibility. The main remaining gap is the precise precondition for expected_version, but an agent has enough context to invoke the 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 description coverage is 0%, so the description must add meaning to record_id and expected_version. It adds 'using the retrieved version' and 'increment version,' suggesting expected_version is an optimistic-concurrency value, but it does not explicitly state matching/failure behavior or how to obtain the retrieved version.

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 clearly identifies this as a soft-delete/archive operation for a record and explicitly distinguishes it from the normal write path by calling it 'Legacy direct write' and naming prepare_write/commit_write as alternatives. The statement that archived records are excluded from ordinary search pins down the resource and outcome beyond the tool name.

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 description gives explicit routing guidance: it warns that this legacy direct write returns REVIEW_REQUIRED and tells the agent to use prepare_write/commit_write instead. It does not fully spell out a decision tree for when archiving is appropriate, but the intended context is clearly implied.

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 provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It reveals the consistent-snapshot semantics, per-operation caps, default event_limit behavior ('omitted, not absent'), per-direction relationship limits, ordered results with item_index, all-or-nothing failure behavior, and the auth boundary between reads and writes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence carries operational information: entry limits, snapshot semantics, per-operation argument reuse, aggregate caps, cursor behavior, failure atomicity, response size, and auth caution. It is front-loaded with the core purpose and uses compact clauses instead of 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 an operation that aggregates multiple read variants, the description covers the essential selection criteria, capacity limits, failure semantics, cursor behavior, and authorization nuance. An output schema exists, so return-value details need not be restated. The only minor gap is that the 'catalog' operation is not explicitly named as list_collections, but the reference is recognizable from the schema discriminator.

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 meaningfully does. It explains that searches accept full-text, include_context returns full records with one-hop links, traverse reuses the traverse tool's arguments with max_nodes capped at 100, and aggregate reuses the aggregate tool's arguments. It does not walk through every nested field, but the operation-level semantics it adds are substantial for the single 'requests' parameter.

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 opens with a specific verb and resource: 'Read 1–10 mixed searches, contexts, traversals or catalogs in one consistent snapshot.' This clearly distinguishes batch_read from individual read operations and write tools by stating both the batching behavior and the resource types involved.

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 description explains when to use this tool rather than single-operation tools: it is for batching 1–10 mixed reads. It also gives important usage constraints like per-operation limits, the total <=100 cap, the 2 MB response limit, and the warning that reads do not authorize writes. It does not explicitly name individual alternatives and say 'use them when…', but the batching intent 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 burden of behavioral disclosure. It does add meaningful behavior: results are ordered and independent, batching is not identity confirmation, and ambiguous or misspelled names should be handled separately. It does not mention side effects, permissions, or what 'same safeguards as resolve_record' actually entails, leaving some behavioral ambiguity.

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, each earning its place: action/scope, return behavior, and a critical caveat. The warning is front-loaded after the outcome rather than buried, and there is no redundant or filler text.

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 batch tool, the description covers the core purpose, output semantics, and a key caveat. It is incomplete around the request object's fields, and the 'same safeguards as resolve_record' reference pushes responsibility to a sibling description. Still, with an output schema present and only one top-level parameter, an agent can likely invoke it correctly after inspecting 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 0%, so the description must compensate. It gives high-level meaning for the request payload ('names/IDs', '1–10') but never maps this to the requests array or explains the nested ResolveRequest fields (query, collection_id, context_record_ids). The count and query intent are covered, but optional parameters are entirely unaddressed.

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 clear action ('Resolve'), a specific resource ('names/IDs'), and a scope ('1–10 ... together'), making it distinct from the single-item sibling resolve_record. It also adds purposeful output semantics ('ordered, independent resolution tickets and candidate context'). The only slight gap is that it references resolve_record's safeguards without defining them, but the core purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than explicit: the '1–10 ... together' phrasing suggests using this tool when multiple names or IDs must be resolved, and the reference to resolve_record identifies the related alternative. However, it never states 'use resolve_record for a single name' or gives when-not-to-use conditions. The warning about ambiguous/misspelled names is guidance for interpreting results, not tool 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 fully discloses critical behaviors: atomicity, audit evidence, freshness/actor/workspace/version checks, 15-minute expiry, safe retry across restarts, and failure semantics including not committing partial items and refreshing stale reviews. This exceeds typical transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at five sentences, front-loading the core action and then detailing checks, expiry, retry, and failure. Each sentence adds value, though the structure could be slightly more streamlined (e.g., grouping related constraints). Overall, it is efficient and well-organized.

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?

The description covers essential aspects: atomicity, validation checks, expiry, retry safety, and failure handling. It does not mention prerequisites (e.g., must call prepare_batch_write first) explicitly, but it is implied by 'prepared batch'. Return value details are presumably covered by the output schema. It is sufficiently complete for a commit 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?

The schema provides no description for action_id (coverage 0%), and the description only references it in the retry context. It implies action_id is the batch identifier but does not explicitly state it is the ID returned by prepare_batch_write. The description partially compensates but could be more explicit about the parameter's origin and purpose.

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 clearly states the tool commits a prepared batch atomically with audit evidence, distinguishing it from siblings like prepare_batch_write and commit_write. The verb 'commit' and resource 'prepared batch' are specific, and the mention of 'all-or-nothing' and checks clarifies its role.

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 description implies it should be used after preparing a batch and provides guidance on retry and failure behavior. However, it does not explicitly contrast with commit_write or commit_import, nor state when not to use it. The context is clear but lacks explicit 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?

With no annotations, the description carries the full burden and does so thoroughly: atomic commit, decision coverage requirements, allowed actions, link dropping/reporting, staleness conditions, and safe retry. These are critical behavioral traits not visible in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence adds operational value. The purpose is front-loaded, and the decision constraints, staleness rule, and retry safety are organized logically 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?

Given that an output schema exists, return-value details are not needed. The description covers decision validation, staleness handling, and idempotent retry – all essential for correct invocation of this commit 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%, and the description fully compensates by explaining the decisions object with allowed actions, record_id semantics, and clarification requirements. It also clarifies that action_id refers to the prepared import action, making both parameters meaningful.

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 ('commit') and resource ('prepared import'), and the atomicity qualifier adds precision. It is clearly distinct from sibling commit tools like commit_write or commit_batch_write by referencing the prepare step.

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 explicitly ties the tool to prepare_import by requiring decisions to match needs_decision and instructing to prepare again if stale. This gives clear when-to-use context, though it doesn't explicitly name alternative commit 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 full behavioral disclosure and does so thoroughly: atomic context revalidation before commitment, 15-minute ticket expiry, dependency-based staleness conditions, idempotency on retry even after restart, and the return of durable IDs and audit. This is rich, non-obvious behavioral context.

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 sentences with no filler: the first states the core action, the second explains expiry and staleness, the third covers idempotency and return behavior. The most important information is front-loaded.

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 commit tool with an output schema, the description covers commit semantics, failure conditions, idempotency, and return value. The only notable gap is not explicitly pointing to prepare_write as the source of action_id, but 'prepared action' already implies that workflow.

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 input schema only provides action_id as a string, so the description adds needed meaning by revealing that action_id is a ticket/prepared-action identifier that expires and is idempotent on retry. It does not explicitly state where action_id comes from, such as a prior prepare_write call, but the 'prepared action' wording gives adequate semantic grounding.

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 clear verb ('Commit') and a specific object ('the prepared action') with meaningful qualifiers: 'exactly' and 'after atomic context revalidation.' The singular action_id and 'prepared action' wording distinguish it from siblings like commit_batch_write and commit_import, though no sibling is explicitly named.

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?

Provides useful operational context: tickets expire after 15 minutes and staleness depends on specific dependency changes, so an agent understands when a commit may fail. However, it does not explicitly say when to prefer this tool over commit_batch_write or commit_import, leaving usage guidance implied rather than explicit.

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 must carry the behavioral disclosure burden. It does reveal legacy status, REVIEW_REQUIRED return behavior, and name normalization, but it does not explain the review workflow, side effects, or what actually happens after REVIEW_REQUIRED.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, immediately warning about legacy behavior and routing the agent to the recommended tools. Every sentence 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 value details are not needed. The description covers the key routing decision well, but leaves gaps around what REVIEW_REQUIRED means in practice and what the description parameter is for.

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 schema has no parameter descriptions, so the description must compensate. It adds useful semantics for 'name' via casefold and collapsed-whitespace normalization, but says nothing about the 'description' parameter.

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 identifies this as a legacy direct write for collections and mentions normalized-name behavior. It is clear enough, though it never states the full purpose in a straightforward sentence like 'creates a collection.'

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 explicitly tells the agent to use prepare_write/commit_write instead, with the reason being that this legacy tool returns REVIEW_REQUIRED. This provides unambiguous when-to-use versus alternative 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 present, so the description carries the full behavioral burden. It discloses the side effect (creating a record and audit event), the REVIEW_REQUIRED response, and the returned UUID, version, and trusted configured local actor. It stops short of fully clarifying whether REVIEW_REQUIRED means the record is persisted or only queued for review, which is a meaningful residual gap.

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 definition is compact and front-loaded: the most important warning about legacy behavior and the alternative comes first. Every sentence adds distinct value, and there is no filler or repetition.

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?

Given the output schema exists, return-value explanation is less critical, and the description covers the key behavioral trap, the side effect, and the search-first precondition. It is less complete on parameter semantics and the precise meaning of REVIEW_REQUIRED, but it still gives an agent enough to decide whether to use the tool or route to the modern alternative.

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 parameter meaning relies entirely on the prose. The description gives only indirect hints that data is a generic JSON object and that title-like names are not unique; collection_id is never explained. This does not sufficiently compensate for the schema silence.

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 clearly identifies a legacy direct-write operation that creates a generic JSON-object record and audit event. It distinguishes itself from the prepare_write/commit_write siblings by labeling itself as legacy and explicitly naming the modern alternative. The core purpose is unambiguous despite the REVIEW_REQUIRED behavior.

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 description tells agents to prefer prepare_write/commit_write instead, making the primary alternative explicit. It also instructs agents to search first because names are not unique, which is a concrete precondition for safe use. This provides both a when-not-to-use and a how-to-use-it-appropriately guideline.

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 provided, the description carries the full burden of behavioral disclosure. It reveals semantic search behavior ('Read all catalog entries by meaning; synonyms can have no shared words'), the workflow coupling ('Incomplete review cannot authorize creation'), and the fact that it returns a discovery_id. It does not state side effects or permission requirements, but 'Review' and 'Returns' strongly imply a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the most important instruction. Most sentences earn their place, especially the semantic-matching note and the creation-authorization constraint. The final phrase 'do not ask routinely' is somewhat unclear and slightly undercuts the otherwise tight structure.

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?

The description covers the tool's purpose, output content, and workflow context, and an output schema exists so return structure does not need explanation. However, the required parameters are not adequately explained, and the relationship between discovery_id and create_collection is implied but not explicit. This leaves a notable gap for a tool meant to gate collection creation.

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 for the opaque `name` and `purpose` parameters. It hints that matching is semantic ('Read all catalog entries by meaning'), which likely relates to `purpose`, but it never explains what `name` represents or how it is used. This leaves an agent guessing about half the required inputs.

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 opens with a specific action and context: 'Review the existing catalog BEFORE collection creation.' It also enumerates the return payload ('full names, purposes, aliases, representative records and lexical suggestions, plus discovery_id'), making the tool's function concrete. It is clearly distinguished from siblings like create_collection and list_collections by its pre-creation discovery focus.

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 description gives explicit timing: use it 'BEFORE collection creation.' It provides behavioral guidance to 'prefer reuse when purpose fits,' and notes that 'incomplete review cannot authorize creation,' signaling a prerequisite workflow. It does not name alternative sibling tools or explicitly state when not to use it beyond the slightly ambiguous 'do not ask routinely,' so it falls just short of a 5.

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 provided, the description carries the full burden of behavioral disclosure. It usefully states that the result is paginated, includes local actor, UTC timestamps, before/after values, and that limit range is 1–100. These details go beyond the schema and give an agent a solid sense of what will happen, though ordering and cursor mechanics are not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise, dense sentences with no filler. The main action and resource are front-loaded in the first sentence, and the second sentence adds only necessary behavioral details. Every sentence 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 a read-only tool with an output schema present, the description covers the key information an agent needs: what history is returned, useful response fields, pagination, and limit bounds. It does not need to explain return values because the output schema exists. A brief mention of ordering or explicit cursor usage would make it fully complete, but the current description is adequate.

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 adds meaning by defining the limit range (1–100) and indicating that cursor is used for pagination. Collection_id is not explicitly described, but its purpose is obvious from the tool name and the phrase 'collection history', so the description provides enough semantic value.

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 opens with the specific verb 'Read' and clearly identifies the resource: paginated collection creation, rename/description, alias, and decision history. This distinguishes it from the sibling tool get_record_history, which concerns record history rather than collection 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 description implies when to use the tool: to read history for a collection, especially around creation, renames, descriptions, aliases, and decisions. However, it does not explicitly state when not to use it or mention alternatives like get_record_history, so the usage context is implied rather than clearly contrasted.

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 behavioral burden and does it well. It discloses limits ('Limits 1–100'), semantics of event_limit=0, per-direction relationship limiting, truncation flags for omitted results, and the explicit follow-on instruction for another hop. This goes beyond a surface-level read and gives the agent a solid mental model of the tool's runtime 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?

The description is a single dense paragraph with no wasted words. It front-loads the primary purpose, then layers limits, truncation, and multi-hop guidance in a logical order. Every sentence contributes either purpose, behavior, or practical usage detail.

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?

The description adequately covers what the tool returns, its constraints, and how to extend to another hop. An output schema exists, so return-value details are not required in the text. The main gaps are minor: no explicit error semantics or authentication needs, but nothing essential for a correct first 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 description coverage is 0%, so the description must compensate. It does: 'Limits 1–100' informs the integer range, 'event_limit=0 omits history explicitly' clarifies a non-obvious default behavior, and 'Relationship limit applies per direction' adds meaning to relationship_limit. record_id is implicitly obvious from 'Get record'. The description adds genuine semantic value beyond the raw 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 description opens with a specific verb and resource: 'Get record/version, one-hop incoming/outgoing links and recent events'. This clearly identifies what the tool fetches and includes useful scope ('including archived records'). It does not explicitly name sibling tools for contrast, but the combination of record, links, and events is distinctive enough to set it apart from siblings like get_record_history or traverse.

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 context is implied through phrases like 'one-hop' and 'recent events', which suggest this is for gathering a bounded context snapshot rather than deep traversal. However, it never explicitly states when to choose this over alternatives such as traverse, get_record_history, or resolve_record. The 'Follow a returned ID explicitly for another hop' line is useful operational guidance, not tool-selection 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 present, so the description carries the full burden. It discloses the ordering (newest-first), page size range (1–100), content (timestamps, local actor, before/after snapshots), precondition (after archive), and pagination behavior. This is rich, accurate behavioral detail beyond the schema.

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 compact sentences with no filler. The core behavior and ordering are front-loaded, and pagination is addressed in the second sentence. Every phrase adds value.

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 an output schema present, return values need no further explanation. The description covers what the tool reads, the ordering, the limit range, the required post-archive state, and how to page through results. Nothing an agent needs to call 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 0%, so the description must compensate. It explains the cursor parameter ('next_cursor' continuation to older events) and the limit's range/ordering, but it does not explicitly describe record_id. Still, the tool name and context make record_id's role evident, and the pagination semantics are well covered.

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 clearly states a specific verb ('Read'), a specific resource ('audit events'), and the scope ('1–100 newest-first'). It also distinguishes the content of the history from simper read tools by mentioning timestamps, actor, and before/after snapshots.

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 description gives a clear precondition ('available after archive') and explicit pagination guidance ('Pass next_cursor to continue to older events'). It does not name sibling alternatives or say when not to use it, but the context is clear enough for an agent to select it appropriately.

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 provided, the description carries the behavioral burden, and it does so well: it discloses the REVIEW_REQUIRED result, the idempotent 'return the existing triple' behavior, the audit side effect, and the legacy status. It does not explain what triggers REVIEW_REQUIRED or what the audit entails, but the key surprises are surfaced.

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 short sentences, all of which carry distinct value: legacy warning, action definition, evidence criterion, and audit side effect. The most important caveat is front-loaded, and 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?

For a simple 3-parameter tool with an output schema, the description covers legacy/replacement routing, idempotency, evidence constraints, and audit behavior, which is strong. It would be complete with a brief clarification of REVIEW_REQUIRED implications or permission requirements, but those are not fatal gaps given the output schema and the explicit alternative.

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?

Input schema coverage is 0% and no parameter descriptions exist, so the description must compensate. 'Directed typed link' and 'active records' add meaning to source_id/target_id/relationship_type, and the idempotency behavior helps interpret what happens when a triple already exists. However, it never explicitly maps each parameter to its value rules or formats, so the compensation is only partial.

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 ('directed typed link'), a concrete action ('Create'), and a fallback outcome ('or return the existing triple'), with scope ('between active records in this workspace'). It clearly separates this from the prepare_write/commit_write workflow and sibling unlink_records.

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 explicitly directs agents to 'use prepare_write/commit_write' and warns that this legacy direct write 'returns REVIEW_REQUIRED', which is strong alternative guidance. The sentence 'Only explicit contextual evidence justifies a link' adds a semantic eligibility condition, though it doesn't enumerate exactly when to prefer link_records over the modern path beyond the legacy caveat.

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 provided, the description carries the burden of behavioral disclosure. It does add useful context by listing the returned fields and the 'max 1000' limit. However, it does not explain what happens when more than 1000 collections exist, whether pagination is supported, or any access or read-only implications, leaving notable gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no filler. It front-loads the verb and resource, then lists the specific data returned and the limit. Every word 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 a parameterless list operation with an output schema, the description covers the essential return contents and a key limitation. It is not overly verbose, though it could be slightly more complete by clarifying pagination or truncation behavior when the max is exceeded.

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 tool has zero parameters, so the description does not need to explain parameter meaning. The '100%' schema coverage is trivial in this case, and the 0-param baseline of 4 applies. The description appropriately focuses on the output rather than inputs.

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 clearly states the tool's action ('Discover') and resource ('collection IDs, normalized names, descriptions and active counts'), and adds a specific limit ('max 1000'). However, it does not differentiate from the sibling 'discover_collections', which appears to serve a very similar purpose, so the clarity is strong but not fully distinguishing.

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 explicit guidance is given about when to use this tool versus alternatives such as 'discover_collections' or 'get_collection_history'. The description provides output contents but no context about prerequisites, search/filter behavior, or situations where another tool would be preferable.

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 discloses atomicity, same-initial-snapshot validation, ordered execution with version checks, no side effects ('Nothing is changed'), and whole-batch rejection with a zero-based item_index.

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 purpose and dense with useful information; every sentence contributes. Minor clarity issues like 'actual clarification' and the vague 'existing single-write discovery workflow' keep it from being fully polished.

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?

Covers nearly all critical behavior for a prepare endpoint: validation snapshot, ordering, version checks, no persistence, failure behavior, and the action_id result. The main gap is not explicitly stating that the returned action_id should be passed to commit_batch_write to apply the batch.

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%, but the description compensates by referencing prepare_write's argument shape and naming review_ids, decision_reason, and optional clarification. It also adds batch-level semantics like the 1–10 limit and successive expected_version requirement, though it does not enumerate operation/arguments fields explicitly.

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 ('Preview'), resource ('existing-record writes'), scope ('1–10'), and outcome ('returns one action_id'). The atomicity and batch nature clearly distinguish it from single-write prepare_write and commit_batch_write.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: use for 1–10 existing-record writes, and explicitly excludes creation/collection changes by directing them to the single-write discovery workflow. However, it does not explicitly name commit_batch_write as the follow-up step or state when single prepare_write should be preferred.

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 discloses that nothing is written, explains the duplicate-checking behavior, the need for resolution tickets for existing record endpoints, and the row limit with error feedback. This is thorough for a prepare-type 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 description is dense but well-structured, with the main purpose front-loaded and a line break separating the high-level description from parameter details. Every sentence adds useful information without fluff, though it is slightly longer than necessary.

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?

Given the existence of an output schema, the description covers the key behavioral outcomes (returns per-row status, needs_decision, preview, action_id) and explains the two-call workflow. It omits explanation of decision_reason and partially covers review_ids/clarification, but overall an agent has enough to invoke the 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 0%, so the description must explain all parameters. It does explain rows and links structures well, and touches on review_ids and clarification in context. However, it does not explain collection_id or decision_reason, which are required, and the description of review_ids is partial. It adds value but does not fully compensate for the missing 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 description opens with a specific verb ('Prepare creating') and resource ('up to 100 records in ONE existing collection'), plus the key differentiator of needing only two calls instead of three. It also contrasts with resolve_record by stating no per-title resolution is needed, making its purpose unambiguous and distinct from 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?

It clearly implies use for batch imports by highlighting the two-call advantage over per-record resolution and explicitly references the similarity rules of resolve_record. It also notes a constraint (very large collections limit rows per call) but does not explicitly name when to avoid it or point to alternative preparation tools like prepare_write or prepare_batch_write.

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 full burden and does an excellent job: states no entities are created, provisional preview IDs must be replaced with commit_write results, reasons/clarification are agent-reported not authenticated consent, and explicit confirmation is required for alias/self operations. This is more behavioral disclosure than most.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a one-sentence purpose and then a compact per-operation field list. It is long but justified by 13 operation variants; a more tabular or bulleted layout would improve scannability, but every sentence 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?

For a high-complexity tool with no annotations, the description covers operation semantics, required argument shapes, provisional ID behavior, and confirmation requirements. It is still missing explicit guidance on review_ids and decision_reason, which are required top-level parameters, though the output schema may cover return shape.

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 compensates substantially by enumerating the exact required fields for each of the 13 operation variants and noting discovery/confirmation constraints. It does not explain top-level parameters review_ids and decision_reason beyond the word 'evidence', and clarification is only addressed parenthetically, so not full compensation.

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 first sentence names a specific verb/resource ('Prepare a concrete write') and immediately differentiates from commit-style siblings by stating it 'creates no entities yet' and returns preview/action_id. This also distinguishes it from direct create_* and commit_write.

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 usage context: use for a single concrete write that needs fresh discovery/resolution evidence, preview, and a later commit. It also instructs when not to ask for additional user approval. However, it does not explicitly compare against prepare_batch_write or the direct create_* siblings, so exclusions are only implied.

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 fully discloses behavioral traits: it covers archives, compares every title and alias in scope, requires context IDs to link to all of them, returns specific fields, handles fuzzy results, defines the 'me' special case, and warns that no match is not proof of absence. This is comprehensive transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but each sentence adds value: purpose, scope, constraints, output, and cautions are all included without fluff. It is front-loaded with the core purpose and structured logically, though slightly long, it remains efficient.

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?

Given the tool's complexity and the lack of annotations, the description covers essential aspects: matching scope, context constraints, output fields, handling of ambiguous results, special 'me' case, and a specific use case. It is complete enough for an agent to call it correctly, especially with an output schema available.

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 explains the query parameter (name, alias, ID) and context_record_ids (require links to all), but does not explicitly describe collection_id beyond a hint in the create_record use case. This partial compensation earns a mid-range score.

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 clearly states the tool's purpose: to resolve a name, misspelling, confirmed alias, or known stable ID, and explicitly includes archives. It differentiates from siblings like search_records and batch_resolve_records by its resolution focus and mentions a specific use case for create_record, making its role distinct.

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 description provides clear usage context, such as requiring clarification or independent identity evidence before writes for fuzzy results, and directs resolution of titles for create_record. However, it does not explicitly name alternatives or state when not to use this tool, though the context is sufficient for an agent to infer appropriate usage.

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 behavioral burden, and it delivers: typed equality semantics (38 never matches "38"), canonical JSON equality where null differs from missing, order_by exclusion behavior, cursor pagination, and the warning that zero matches does not establish nonexistence. These are non-obvious traits an agent must know before calling the tool correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place; it uses compact labeled sections for each parameter and front-loads the core purpose. There is no repetition of schema names or filler, and the dense formatting makes complex semantics scannable.

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 search tool with no annotations, this is a remarkably thorough description covering matching rules, type strictness, date handling, sorting, pagination, and cursor reuse. The main gap is collection_id, which is not explained at all, and the limit parameter is left implicit, so a fully self-sufficient agent would still have small uncertainties.

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 for most parameters: text, query, where, linked_to, order_by, filters, and cursor are all explained in meaningful detail. However, collection_id is never mentioned, and limit semantics are only implied via the 1–100 preview bound, leaving two parameters underdocumented.

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 opens with 'Search active records', a specific verb plus resource, and immediately scopes the operation to active records only. It then precisely differentiates the text and query modes, so an agent knows exactly what the tool does. The purpose is unambiguous even though no sibling search tool exists to distinguish it from.

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 description gives an explicit selection rule: 'Use text when the user describes something by content rather than exact title', which is exactly the kind of when-to-use guidance agents need. It also states that order_by is not combinable with text. It does not compare this tool against sibling alternatives, so it stops just short of a 5.

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 provided, the description fully bears the responsibility for behavioral disclosure. It explicitly states that archived records are included, that truncated flags indicate limits were hit, and that reads do not authorize writes. These are important behavioral traits beyond what the schema or output schema would convey. No contradictions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and information-rich, with no wasted words. It front-loads the core purpose and example before diving into parameter details. Each sentence adds value, covering return values, limits, filtering, archived records, and permission caveats. It is slightly long but appropriate for the tool's complexity.

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?

Given the tool's complexity (6 parameters, output schema present), the description covers the essential aspects: what it returns (preview, depth, shortest path, relationships), limits, filtering, archived records, and the permission caveat. The existence of an output schema covers return structure details. The only notable gap is the lack of explanation for the direction parameter, which is a meaningful omission for a traversal tool. Overall, it is nearly complete but falls short of exhaustive.

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 explains relationship_types (restricts which link types are followed), collection_id (filters returned records without blocking routes), and max_nodes (caps reached records with truncation flags). It also clarifies max_depth as 1–4 hops. However, it omits any explanation of the direction parameter (outgoing/incoming/both), which is non-obvious and would benefit from a brief clarification. Start_record_id is self-evident.

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 clearly states the tool walks explicit links breadth-first up to a depth, with a concrete example chain (person -> applications -> openings/interviews -> feedback). It specifies the resource (links) and the operation (walk), and the unique focus on graph traversal distinguishes it from siblings like search_records or batch_read. The purpose is unambiguous and well-scoped.

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 description provides clear context for when to use the tool (traversing relationships) and includes a caution that reading does not authorize writes, guiding the agent to resolve before mutating. However, it does not explicitly name alternatives or state when not to use it, such as when a simple batch read would suffice. It lacks explicit exclusions but the context is sufficiently 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?

No annotations are present, so the description carries the burden. It discloses that the tool returns REVIEW_REQUIRED, that it is a direct legacy write, and that it preserves full relationship details in source history. It does not cover auth or failure modes, but for a one-parameter tool the key behavioral caveats are present.

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-load the most important warning (legacy, REVIEW_REQUIRED, alternative) before the instruction. 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 simple one-parameter tool with an output schema, the description covers purpose, legacy status, the primary caveat, the alternative, and parameter semantics. It doesn't describe exact return structure, but the output schema is already provided; minor missing details are auth or prerequisite conditions, which are not necessary for an agent to decide against using this tool or to call it with relationship_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?

Schema coverage is 0%, so the description must compensate. It does by specifying that relationship_id is the link's own ID (not record IDs), and that removing it preserves relationship history. This adds meaningful semantics beyond the bare parameter name, though it doesn't describe format or type beyond the schema's string.

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 identifies a specific action ('Remove a wrong link by its own ID') and resource (link/relationship records), and explicitly distinguishes the tool from the modern write flow by labeling it 'Legacy direct write' and naming prepare_write/commit_write. This is more than a restatement of the tool name.

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 explicitly instructs agents to use prepare_write/commit_write instead, and frames this tool as a legacy fallback for removing a wrong link. That gives a clear when-not condition and names the alternative, satisfying the highest bar.

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 full behavioral burden and delivers: it discloses the REVIEW_REQUIRED result, shallow-merge semantics (omitted keys remain, null is stored), the need for the retrieved version, and the VERSION_CONFLICT retry prohibition. This is substantive, non-obvious 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?

Three dense sentences, each earning its place: the legacy warning is front-loaded, merge semantics follow, and conflict guidance closes. No fluff or repetition of the schema.

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?

Covers the essential behavioral traps, version requirements, and the preferred alternative. With an output schema present, not detailing return values is acceptable; a minor gap is not explaining what to do with REVIEW_REQUIRED or when this tool is still appropriate.

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 for all three parameters. It does well for changes (shallow-merge top-level fields, null behavior) and expected_version (supply retrieved version, conflict handling), though record_id is left 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 action ('direct write') on record data and explicitly contrasts with the preferred sibling flow (prepare_write/commit_write). It also describes the shallow-merge behavior, making the tool's function unmistakable beyond its name.

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 directs agents to use prepare_write/commit_write instead, signaling that this is a legacy path. It does not spell out any specific scenario where update_record should be chosen over its siblings, but the exclusion is clear enough.

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