JSONPad

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: atomic all-or-nothing semantics ('if any change would be refused, nothing is written'), the exact permission requirements (sync-schema plus per-change permissions, flows need an all-permitted token), background index builds, and the jsonpad sync-schema deployment suggestion.

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 but front-loaded: the primary action and its atomicity come first, followed by prerequisites, then destructive-flag conditions. Every sentence carries actionable information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter destructive mutation with an output schema, the description covers the prerequisite tool, permission model, destructive flag interplay, background execution, and failure semantics. The output schema handles return values, so nothing an agent needs 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 baseline is 3. The description goes further by linking prune to the required confirmDestructive: true flag and describing the delete consequences of prune, adding cross-parameter meaning the schema doesn't convey. allowRebuild/allowDestructive remain schema-only, so it isn't a full 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?

The description opens with a specific verb+resource: 'Create and update lists, indexes, write rules and flows to match a schema sync document.' That scope is clearly distinct from sibling tools like create_list or update_index (single-resource) and from plan_schema_sync (dry run).

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 to the alternative: 'Run plan_schema_sync first and show the user the plan.' It also gives conditional usage rules for prune (needs confirmDestructive: true) and points at wait_for_index for background index builds. Nothing is left to inference.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses meaningful behavior: the index builds asynchronously, consumers fail with INDEX_BUILDING until buildStatus is ready, and wait: true polls at 1 metered request per poll with an explicit cost statement ("1 request, plus the polls"). It does not cover what happens on name/pathName conflicts or permission requirements, so it stops 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?

Three sentences, front-loaded with the core action and then the async/cost caveats; little waste. There is mild redundancy with the per-flag schema descriptions, keeping it from 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?

An output schema exists so return values need not be explained, and the description covers the critical non-obvious behaviors (async build, INDEX_BUILDING failure, metered polling cost). The main remaining gap is conflict/error behavior for a non-idempotent creation 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 80%, so the schema already documents nearly all 15 parameters, including the alias, guard, sorting, and filtering flags. The description paraphrases those same flags (alias/order/filter/search/guard) without adding syntax or constraints beyond the schema, so baseline 3 is appropriate.

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 ("Index a value in a list's items") and enumerates the purposes the index enables (alias, order, filter, search, guard). It does not explicitly differentiate itself from close siblings like update_index, rebuild_index, or list_indexes, so an agent must infer it is the creation path.

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 through the enumerated index capabilities and the wait polling condition, giving an agent a reasonable sense of intent. However, there is no explicit routing guidance for when to use this versus rebuild_index, update_index, or wait_for_index, which are the natural alternatives.

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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds meaningful context: schema and rule validation of data, rule lookup cost per item read, and variable substitution semantics with examples. It also mentions return of metadata and etag. This goes beyond annotations and aids correct invocation.

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-loads the core action and carefully includes cost and return info, but the sentence about variable substitution is lengthy and could be tightened. Overall, no wasted words for the complexity involved.

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 complexity (8 params, rule validation) and the presence of an output schema, the description covers what an agent needs: validation, cost, variable substitution, and return shape. It doesn't need to explain return values further because an output schema exists.

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 63%, so the schema documents most parameters. The description adds detail about $jsonpad-var syntax but doesn't clarify other parameters like readonly or activated beyond their schema presence. Baseline 3 is appropriate given partial coverage.

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 ('Add an item to a list'), consistent with title and annotations. Distinguishes from siblings like update_item, merge_item_data, patch_item_data, replace_item_data by being the create operation.

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 it (creating a new item), but doesn't explicitly differentiate from other write tools or state preconditions like required permissions. It's adequate but leaves the agent to infer when to choose create_item versus update_item.

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 the mutation profile (readOnly=false, non-idempotent, non-destructive), so the bar is lower. The description adds value the annotations cannot: non-compiling or failing rules abort the entire create (atomic failure), diagnostics arrive in details, and '1 request' signals cost. It doesn't explain what happens to a partially-created list beyond the refusal, but the failure semantics are notably well disclosed.

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

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

Four terse sentences: purpose first, alternative routing second, failure semantics third, cost last. Zero filler and nothing redundant with 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?

With annotations covering the safety profile, an output schema covering return values, and 92% schema coverage for parameters, the description supplies exactly the missing glue: alternative routing and atomic failure behavior. Complete 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 92%, so the schema already documents all 13 parameters and the baseline is 3. The description adds cross-cutting meaning for the rules/rulesTests pair (compilation and test failures block the create) but no per-parameter syntax or format detail beyond that.

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 ('Create a list') and immediately distinguishes itself from the bulk path by pointing at plan_schema_sync/apply_schema_sync. An agent can identify the tool's role 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 bulk scenario (several lists with indexes and rules) to the schema-sync siblings, which is real when-to-use guidance. It doesn't state a when-not for the single-list case, but the alternative is named clearly.

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 carry the generic destructive/idempotent profile, but the description discloses non-obvious consequences: dependent ordering, filtering, searching and alias lookups stop working, and un-hiding guard values changes who can read them. It also quantifies request cost including the conditional guard check, which is real behavioral detail 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?

Four short sentences, each carrying distinct information: action, data-safety scope, blast radius, refusal gate, then request cost. The most important constraint (data is untouched) is front-loaded, 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?

An output schema exists, so return values need no explanation, and the description still covers the destructive blast radius, the authorization-style gate, and request cost. Nothing an agent needs to invoke this 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 baseline is 3, but the description adds genuine semantics the schema alone lacks: confirmUnguard is not just a flag but the gate that makes an otherwise-refused guard-index deletion possible. list/index 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+resource ("Delete an index") and immediately scopes it against the broader data model ("Item data is untouched"), which cleanly separates it from sibling delete_item, delete_item_data, and delete_list. An agent can pick this tool without opening any sibling schema.

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

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

Gives a concrete blocker: deleting a guard index is refused unless confirmUnguard is true, which tells the agent both the condition and the required flag. It does not, however, name alternatives (rebuild_index, update_index, delete_list) or say when deletion is the wrong choice versus those.

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 declare destructiveHint=true and non-idempotent, and the description adds non-obvious behavior beyond that: the deletion is recoverable (event with restorable: true, restore_item re-creates with the same id) and the precondition failure mode (ITEM_PRECONDITION_FAILED, nothing written). It does not spell out auth requirements or a return shape, but the recovery and failure semantics are the material additions.

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, front-loaded with the operation, then recovery, then the concurrency rule. The trailing '1 request' is terse but useful cost context; nothing here 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?

With annotations covering the safety profile and an output schema handling return values, the description supplies exactly what structured fields cannot: reversibility, the sibling tools that enable restore, and the ifMatch precondition rule. Nothing needed to call this 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 item, list, and ifMatch are already fully documented in the schema, including the same precondition semantics the description restates. The description adds only a light usage rule for ifMatch and no new format or value information, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete an item') and immediately distinguishes itself from its siblings by naming the recovery path (list_events + restore_item) that delete_item_data and delete_list do not share. An agent can tell this apart from the other delete_* tools without opening any schema.

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

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

Gives clear conditional guidance: pass ifMatch when the write is based on something you read, so the delete only fires if nobody changed the item. It does not explicitly contrast itself with delete_item_data or explain when not to delete, but the operating context is unambiguous.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful operational context — the etag precondition pattern and the '1 request' cost signal — though it doesn't expand on failure/partial-write behavior beyond what the ifMatch schema field already states.

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

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

Three short sentences, front-loaded with the core action and the disambiguation rule, with no redundant restatement of the title or 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?

Given a fully documented 5-parameter schema, an output schema, and annotations covering safety and idempotency, the description supplies exactly the missing pieces — scope differentiation and precondition guidance — and nothing more is needed.

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 goes further by characterizing the pointer target semantically ('an object field or an array element') and by restating the ifMatch precondition contract, adding meaning beyond the raw field list.

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 ('Remove the value at a pointer from an item's data') and clarifies the granularity by naming the sibling it is not ('To delete the whole item, use delete_item'). An agent can distinguish it from delete_item, replace_item_data, and patch_item_data without opening a schema.

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

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

Explicitly routes the agent: whole-item deletion goes to delete_item, partial deletion goes here. It also gives the operational condition for ifMatch ('Pass the etag you read as ifMatch'), so the usage context is unambiguous.

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 idempotentHint=false, but the description goes well beyond them: loss is permanent and irreversible, the pathName is freed immediately while contents are purged asynchronously in the background, protected lists with items are refused, and the call costs 1 request. This is unusually rich behavioral disclosure for a mutation 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?

Five tight sentences, front-loaded with the destructive outcome, then the permanence/async behavior, then the refusal condition and confirmation directive. Every sentence carries distinct, load-bearing information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive two-parameter tool with an output schema already covering return values, the description supplies everything an agent needs: irreversibility, immediate vs. background effects, the refusal edge case, and the user-confirmation requirement. No material gap remains.

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% with only two parameters, so the schema already documents that 'list' accepts an id or pathName and that 'confirm' must repeat the same value. The description adds a workflow note about confirming with the user but no additional parameter-level meaning, so the baseline of 3 is appropriate.

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 ("Permanently delete a list") plus the cascade scope ("with all of its items and indexes"). It explicitly distinguishes itself from the item-level deletion path ("Unlike an item, a deleted list can't be restored"), so an agent can tell it apart from delete_item 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?

Gives a clear precondition ("A protected list that still has items is refused") and a procedural directive ("Confirm with the user first"), which is exactly the guidance needed before a destructive call. It implies the item-deletion alternative via the restore contrast but doesn't name a sibling tool explicitly, keeping it 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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses the required sync-schema permission, clarifies that this permission alone suffices to read structure, notes conditional flow data for fully-privileged tokens, and states the cost as "1 request" — exactly the auth and rate context annotations cannot carry.

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 tight sentences, front-loaded with what is exported, then usage, permission and cost; no redundant restatement of the name. The opening fragment reads awkwardly but wastes no 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?

With an output schema present, return shape need not be explained, and the description covers content scope, filtering, permission prerequisite and request cost. Only a pointer to a sibling alternative is missing, a minor gap for a read-only export.

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 schema already documents lists, scope and tagged. The description adds only the intent ("Filter by scope, tags or lists on big accounts"), with no syntax or precedence detail beyond the schema, making the baseline 3 appropriate.

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 title and opening phrase state the resource and output format precisely: the account's lists, indexes and write rules exported as a schema sync document keyed by pathName. It is distinguishable from apply_schema_sync/plan_schema_sync by framing itself as the read/export side of schema sync, though the opening is a verbless fragment that leans on the title for its action.

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 easiest way to start managing an existing account with schema sync" gives a clear adoption context, and "Filter by scope, tags or lists on big accounts" tells the agent when the optional params matter. It does not name an explicit alternative (e.g. plan_schema_sync) or state when not to use it, so it stops short of the 5 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: snapshots reflect post-event state, guarded values are omitted from snapshots exactly as from item data, and '1 request' signals cost. It does not mention permission or rate-limit specifics.

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 compact sentences, front-loaded with what the tool returns and then the routing case. No filler; every clause adds information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return shape, and it correctly focuses on the one thing an agent must know: how to obtain a stale item version. Coverage of the other resource types' prerequisites is left entirely to the schema, which is acceptable given 88% schema coverage and required-parameter enforcement.

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 88%, so the baseline is 3. The description goes slightly beyond by explaining what the snapshot contains and emphasizing that guarded values are excluded, which gives meaningful context for includeSnapshot and the returned payload semantics.

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 ('One event, with its snapshot') and immediately clarifies the resource scope and return payload. It also distinguishes itself from the sibling get_item by naming the version case it covers, so an agent can separate the two 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 says this is the route for reading an item version too old to fetch via get_item's version, which is a real when-to-use with a named alternative. It stops short of covering the other resource types (list/index/identity) or when not to use it, so it is clear but not exhaustive.

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 readOnly/idempotent/destructive=false, yet the description adds substantial value beyond them: the returned etag to use as ifMatch, guarded pointers invisible to this token, the ITEM_VERSION_NOT_RETAINED error path, and request counting (1 request, +1 first use of a list unless get_list was called). This is rich operational context an agent needs.

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 what it returns (metadata/data) before behavioral details, and every sentence carries information. Some phrasing is dense and slightly awkward ('the plan keeps fails'), costing a point but not impeding comprehension.

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 needn't be described, and the description still covers the key behaviors: versioning limits, etag/guarded semantics, and request cost. For a 7-parameter read tool this is largely complete, with only minor gaps around the includeData/includeGuarded toggles.

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; the description still earns extra by clarifying pointer-vs-path intent and the version-retention constraint that governs the 'version' parameter. It adds meaning beyond the schema's own field docs, though it does not re-explain includeData/includeGuarded.

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 and enumerates the scope variations it supports: metadata and data, part of data via pointer or path, current or older version. An agent can immediately tell this is a point-read of a single item, distinct from list_items/search_items, without opening a schema.

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

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

Gives explicit routing for the failure case ('a version older than the plan keeps fails... read it from its event with get_event instead') and notes the get_list interaction for request cost. It lacks broader when-not guidance versus siblings like search_items or list_items, but the conditional alternative is clearly 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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds non-obvious operational context: a truthful request cost ("2 requests (1 without indexes)") and an authorization-conditional disclosure (write rules and rule tests appear only for tokens that can update the list). These are exactly the traits 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?

Front-loaded with the payload and the routing advice in three tight sentences with no filler. The first sentence is a long enumerated run-on, but every clause maps to a real field group rather than 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 two-parameter read tool with an output schema, the description covers scope, cost, and conditional auth behavior, which is sufficient to call it correctly. Detailing the return payload is somewhat redundant given the output schema exists, leaving minor room for improvement rather than a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining what the includeIndexes switch actually yields (buildStatus plus a per-index usage hint covering sort/filter/search/alias/guard behavior), which makes the flag's tradeoff legible. The `list` identifier format is 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?

Opens with a specific verb+resource and enumerates the exact payload: metadata, JSON schema, flags, tags, itemCount, write rules/rule tests, and indexes with buildStatus and usage hints. An agent can distinguish this from list_lists, get_item, or list_indexes without opening any 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?

"The recommended first call before reading or writing an unfamiliar list" gives explicit when-to-use guidance, and "(only for a token that can update the list)" states a precondition. It stops short of naming alternatives (e.g. list_indexes when only indexes are needed, or the 1-request mode without indexes), 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds real context: the default/rolling window behavior and the '1 request' cost indicator, plus what list stats contain (rule refusals).

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 fragments: scope first, then the notable list-specific detail, then a cost indicator. Nothing is padded and 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?

With an output schema present, return values need no explanation, and the annotations plus schema cover safety and parameter detail. The only gap an agent might want is guidance on related activity tools, 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 schema already explains every parameter including the resource enum and the list/item/index/identity dependencies. The description restates the resource choices and the days window without adding syntax or format detail beyond the schema, so baseline 3 applies.

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 ('activity counts') and enumerates the four scopes (list, item, index, identity) with a time window. It does not differentiate itself from related siblings such as list_rule_denials or list_events, so it stops short of a 5.

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

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

Usage is implied by the scope statement and the resource enum, but the description never says when to prefer this over siblings that also surface activity data (list_rule_denials, list_events, get_event). No prerequisites or exclusions are given.

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 readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses that the token value is never returned, that latency cost is '1 request', and that the call doubles as a token validity check.

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 what is returned, followed by when to call it and a cost note. Dense but every clause earns its place; the long return-field enumeration is the only mild bloat, partially redundant with the output 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?

For a zero-parameter, read-only diagnostic with an output schema and full annotation coverage, nothing needed to invoke it correctly is missing — trigger conditions, cost, and the security guarantee on the token value are all present.

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 takes zero parameters, so the schema carries nothing to interpret and the baseline is 4. The description appropriately spends its words on returned fields rather than nonexistent 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?

States a specific verb+resource (get token info) and enumerates exactly what it returns: permission rules, plan limits, monthly usage counters. No sibling tool overlaps with this diagnostic scope, so an agent can distinguish it immediately.

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 triggering conditions: 'Call it first when anything fails with an authentication or permission error, and before a large batch of writes.' This is when-to-use guidance tied to concrete failure modes, with no alternatives needed since no sibling covers this.

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 readOnly, idempotent and non-destructive, so the safety bar is low. The description adds real behavioral context on top: no snapshots (unlike get_event) and the cost/latency signal '1 request'. It stops short of stating rate limits or page-size behavior 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?

Front-loaded with the core purpose, then the get_event contrast, then the restorable workflow. Every clause carries information, though the mid-sentence density on restorable makes it slightly harder to parse than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. Given 13 parameters, an output schema, and rich annotations, the description covers exactly the gaps an agent needs: the get_event distinction and the restore-point discovery 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?

Schema description coverage is 92% (high), so the baseline is 3. The description still adds meaning beyond the schema for the restorable parameter, tying it to restore_item semantics and to the item-deleted event, which the schema field only says 'just the events restore_item can restore'.

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 ('list ... history of a list, item, index or identity') including what the events contain (what happened, when, at which version). It explicitly distinguishes itself from the sibling get_event by noting this one returns events 'without 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?

Gives a concrete when-to-use rule for the non-obvious case: restorable:true lists only events restore_item can go back to, presented as 'this is how to find restore points'. It also routes between this tool and get_event. It lacks any explicit when-not guidance (e.g., when to prefer list_items or search_items instead).

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is low. The description adds pagination ('a page of') and a cost signal ('1 request'), which is meaningful context beyond the structured fields.

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?

Telegraphic and front-loaded: the resource is named first, then the filtering rule, then the sibling relationship. No wasted sentences, though the fragment style borders on terse for a 13-parameter tool.

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 13-parameter filtered list, the description explains only one filter and leaves most of the query surface unaddressed. Output schema exists so return values need no explanation, but the parameter-level guidance gap is significant.

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 only 38% across 13 parameters, and the description compensates for almost none of it, mentioning only pathName filtering while name, alias, guard, order, activated, valueType, and defaultOrderDirection remain undocumented anywhere.

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 (list a list's indexes) and notes return content (buildStatus, usage hint). It also differentiates from the sibling get_list, which 'includes every index too', so an agent can pick between them without opening schemas.

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 rule ('Filter by pathName to find one index') and routes the agent away from get_list when pagination/filtering is desired. No explicit when-not or exclusion beyond that.

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 cover the safe-read profile, and the description adds substantial behavior beyond them: data is omitted unless includeData/path is set, an index that is building fails with INDEX_BUILDING, and it quantifies request cost including the extra guard-index read on first data access per session. That is exactly the operational context an agent cannot get from 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 and every sentence carries technical weight with no filler. It is dense and unformatted as a single paragraph for 14 parameters, which slightly hurts scannability, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be re-explained, and the description fills the tricky gaps: includeData/path interaction, filter operator syntax, order values, and the INDEX_BUILDING failure. Remaining minor gaps (e.g. how readonly/activated filtering interacts, pagination termination) are largely covered by 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 coverage is 86%, so the baseline is 3, but the description adds real meaning: string indexes match partially, number indexes take lt:/lte:/gt:/gte:, date indexes take before:/after:, and order accepts specific fields or a sorting index pathName. This operator-per-index-type mapping goes beyond the schema's single example.

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?

Opens with a specific verb+resource+scope: 'A page of a list's items', making clear it is a paginated, list-scoped read. The behavior is distinguishable from siblings like search_items or get_item because it is explicitly bound to a single list and its filtering/sorting indexes.

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 points at get_list for discovering filtering indexes and hints that calling get_list avoids an extra request, which is useful routing context. However, it never states when to use list_items versus search_items or get_item, and gives no explicit exclusions, so usage is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: pagination behavior ('a page of'), the cost signal '1 request', and a disclosure of what is deliberately excluded (schemas, write rules).

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 terse sentences, front-loaded with the scope and output summary, then the sibling routing, then the cost note. No filler; every clause carries 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a 13-parameter listing tool the description never addresses the filter/order surface, which is a meaningful gap even if the schema partially covers it.

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 only 54%, and the six boolean filters (pinned, readonly, realtime, activated, indexable, protected) carry no schema description at all. The description says nothing about filtering, ordering, pagination parameters or the tag AND/OR semantics, so it does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (lists) with explicit scope: 'a page of the account's lists that this token can see'. It also previews the returned data (flags, tags, item counts) and distinguishes itself from get_list by naming what it omits. An agent can tell it apart from get_list, create_list and update_list without opening any 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 to get_list for schemas and write rules, implying this tool is the enumeration surface rather than the detail surface. There is no explicit when-not beyond that single routing note, so it stops short of a full 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?

It discloses several behavioral traits beyond annotations: limit of 50 entries, newest-first order, potential latency ('A refusal can take a moment to appear'), required token permissions ('update on the list'), and request cost ('1 request'). It doesn't explain output format, but an output schema exists.

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 tight paragraph, front-loaded with the key action and result, and every sentence adds useful information without repetition or fluff.

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 simple input schema, read-only annotations, and the presence of an output schema, the description is nearly complete. It covers the data returned, latency, relevant sibling tool, and auth needs. One minor gap: it doesn't mention that the list must exist, but that's inferred.

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?

With 100% schema description coverage for the single parameter, the baseline is 3. The description adds practical context about the parameter's role (the list whose rules refused writes) and clarifies that the token needs update permission, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope: 'the last 50 writes the list's write rules refused, newest first.' It precisely distinguishes itself from sibling tools like list_events and test_list_rules by focusing on denied write attempts and their details.

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 provides clear context for when to use it (inspecting rule denials) and directs the agent to use test_list_rules for replaying a denial. However, it does not explicitly state when not to use it or compare to other diagnostic tools like get_event.

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 mark this as destructive, non-idempotent and non-read-only, but the description adds merge semantics the agent cannot infer: unmentioned fields are preserved, arrays are concatenated rather than replaced, and writes are conditional on the etag. The single 'safe way to change some fields' phrasing sits slightly in tension with destructiveHint=true, since mentioned fields are still overwritten, though this is not a true contradiction.

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 merge behavior and no filler; the trailing '1 request' is a useful cost signal. The middle sentences are dense and clause-heavy, which slightly hurts scannability, but every sentence carries 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Combined with the description's coverage of merge semantics, array behavior, alternatives and preconditioning, an agent has everything needed to call this 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 100%, so pointer, ifMatch, item and list are already fully documented in the schema with examples (e.g. RFC 6901, ITEM_PRECONDITION_FAILED, alias/id semantics). The description only adds the 'guard indexes' nuance for pointer, which is marginal beyond the structured data, so the baseline 3 is appropriate.

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 ('deep-merge a value into an item's data'), including the scoped variant (into the value at pointer). It explicitly distinguishes itself from the sibling tools patch_item_data and replace_item_data, so an agent can route between the three without opening schemas.

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 the selecting condition directly: 'fields you don't mention are left alone, so this is the safe way to change some fields.' It also names the alternative with its condition ('use patch_item_data or replace_item_data at the array's pointer to replace one'), covering the main ambiguous case (array handling).

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, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them: 'All or nothing' (atomicity), 'Needs the sync-schema permission' (auth requirement), and the dryRun default-true workflow plus '1 request' cost hint. It could go further on what happens to indexes that were already managed by the target scope, but the added context is substantive.

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 prose is dense and front-loaded, leading with the core action before the selection modes, dryRun workflow, and permission requirement. The telegraphic style ('1 request.', 'All or nothing.') is efficient, though the final fragment is slightly clipped rather than fully self-explanatory.

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 4-parameter destructive mutation with an output schema (so return values need no explanation), the description covers purpose, selection, atomicity, permissions, and the dryRun sequence. It is nearly complete; the only residual gap is target-scope index side effects, which the phrase 'with the indexes the scope manages' only partially addresses.

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 schema already documents all four parameters and the baseline would be 3. The description nevertheless adds semantics not in the schema: scope: null is explained as 'release them from schema sync', and fromScope is characterized as 'Move every list this scope manages, instead of lists' — clarifying the mutual exclusivity intent.

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+resource: 'Move lists to another schema sync scope,' and immediately names the sibling operations it is not (plan_schema_sync/apply_schema_sync territory) by covering assignment and release. It also distinguishes the three distinct outcomes (move, assign unmanaged, release via scope: null), which an agent can act on 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?

It states selection modes explicitly ('Choose lists by id or pathName, or every list of fromScope') and gives a concrete when-to-use example ('e.g. to rename a scope'). The dryRun workflow instruction ('show the user the plan, then call again with dryRun: false') is a precise two-step usage directive rather than generic 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?

Goes well beyond the annotations (destructiveHint, idempotentHint) by disclosing atomicity ("All operations apply, or none"), the guarded-value refusal rules including which operations are rejected, and the concurrency contract via ifMatch/ITEM_PRECONDITION_FAILED. These are exactly the behavioral facts an agent cannot recover from annotations or 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?

Dense but front-loaded: purpose, then examples, then atomicity and guard/etag rules. Every sentence carries information, though the guarded-value sentence is clause-heavy and takes a second read.

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 a full output schema, complete parameter descriptions, and annotations covering the safety profile, the description supplies the remaining essentials: PATCH semantics, atomicity, guard behavior, and optimistic concurrency. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: relative path resolution when pointer is set, "Pass the etag you read as ifMatch", and the caution on overwriteGuarded ("Only if the user means to"). It does not explain returnData's interaction with output, but the added semantics exceed the schema alone.

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 (apply JSON Patch operations to an item's data) and pins down the operation model by citing RFC 6902 and giving concrete examples. It implicitly distinguishes itself from whole-document siblings like replace_item_data, but never names the sibling actually used for a full overwrite, so routing is inferred 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?

"Best for surgical edits: replacing an array element, removing a field, appending with path '/list/-'" gives a clear when-to-use signal, and the guarded-value paragraph adds when-not (writes over guarded values are refused). No alternative tool is named, so the agent must still infer that a full replacement belongs to replace_item_data.

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 readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is known. The description adds genuine context beyond that: it performs local validation at no cost before sending, requires the sync-schema permission, costs 1 request, and produces warnings/errors and blockedBy on refusal. That is the kind of behavioral detail an agent cannot get from 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 and safety ('without changing anything') are front-loaded, followed by the result shape, the required ordering, and the operational facts. Dense but every clause earns its place; the long first sentence is the only mild strain.

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 preview tool with annotations covering safety and an output schema covering return structure, this is complete: it specifies ordering (before apply_schema_sync), permission requirement, cost, and the refusal signal (blockedBy). 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 100% and the schema itself documents prune, document, allowRebuild and allowDestructive with defaults and consequences. The description mentions that the document is validated against the sync document schema locally, but adds no syntax or format meaning beyond what the schema already provides, so baseline 3 is appropriate.

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 ('plan a schema sync', 'what applying a schema sync document would do, without changing anything') and enumerates the exact output surface (lists, indexes, flows, per-field create/update/adopt/delete/no-op). This is unmistakably distinct from the sibling apply_schema_sync, which the description names.

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

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

Explicitly states when to use it ('Always call this before apply_schema_sync') and what to do with the result ('show the user the plan'), naming the alternative tool. The when-not is implied by the contrast with apply_schema_sync.

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?

Adds behavior beyond the annotations: failed builds are never auto-retried, non-failed indexes produce a named error code, and wait:true changes the call into a polling loop billed per poll. Annotations only state it is a non-idempotent, non-destructive write; the description supplies the operational semantics.

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

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

Three tight sentences, front-loaded with purpose and precondition, then error behavior, then the wait/cost tradeoff. Nothing is redundant or 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?

With an output schema present, return values need no explanation. The description covers precondition, refusal behavior, and the polling/cost implication of the optional parameter, which is everything an agent needs to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: wait:true drives polling and each poll is a metered request ('1 request, plus the polls'), which quantifies the cost tradeoff of that flag. 'list' and 'index' get no extra detail 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+resource with a precise precondition: 'Start a new build of an index whose last build failed.' The condition (failed-only) cleanly separates it from create_index/update_index/wait_for_index without needing the schemas opened.

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 an explicit when-to-use ('once the cause is fixed') and an explicit when-not ('an index that isn't failed is refused with INDEX_BUILD_NOT_FAILED'). It does not name sibling alternatives such as wait_for_index for monitoring an already-running build, so it stops short of full routing guidance.

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

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

Annotations declare destructive=true and idempotent=true, but the description adds real substance beyond them: that a guarded value would be silently deleted and the write refused unless overwriteGuarded is set, the ITEM_PRECONDITION_FAILED semantics tied to ifMatch, and the cost (1 request plus 1 to find guard indexes the first time). This is a mutation tool with a non-obvious failure mode, and the description surfaces it.

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, front-loaded with the core action before the guard-index caveat and the etag guidance. Tight and information-dense, though the guard-index sentence is long enough to require a careful read.

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 explanation, and the description still covers the safety profile, the precondition mechanism, the guarded-value hazard, and request cost. Nothing an agent needs in order to invoke this 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 coverage is 100%, so the baseline is 3, but the description adds usage semantics the schema alone does not: which etag to supply for ifMatch and the caution that overwriteGuarded should only be used 'if the user means to' delete guarded values.

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 ('replace') plus resource ('an item's whole data') and precise scope ('or the value at pointer'). It explicitly names the sibling alternatives merge_item_data and patch_item_data, so an agent can distinguish this tool without opening any 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?

States the exact refusal condition (a replace covering a guarded value) and routes the agent to alternatives ('use merge_item_data, patch_item_data or a narrower pointer instead'). It also gives the when-condition for ifMatch ('Pass the etag you read as ifMatch') and the trigger for overwriteGuarded.

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?

Adds rich behavior beyond the annotations: permission requirement, schema/write-rule validation, the fact that restoring twice yields two versions, and the specific failure ITEM_UNABLE_TO_RESTORE when restoring to the current version. This is consistent with idempotentHint=false and destructiveHint=true, sharpening rather than repeating them.

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 core action first, then prerequisites, failure modes, and request cost. The opening sentence's long parenthetical is slightly heavy but every clause carries operational 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?

For a destructive, non-idempotent mutation with an output schema, the description covers what is restored (data, description, tags, readonly, activated), permission/auth needs, error codes, and the precondition behavior implied by ifMatch. Nothing an agent needs to invoke 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 coverage is 100% so baseline is 3, but the description adds real meaning: a deleted item must be supplied by original id and is re-created with it, which goes beyond the schema's 'its id or alias value'. It also ties eventId to events discoverable via list_events.

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 ('put back as it was at an event') and resource, and precisely enumerates the four event types it restores to ('item-created, item-updated, item-restored or item-deleted'). An agent can distinguish this from update_item or patch_item_data purely from the description.

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 context: events must be found first via list_events with restorable: true, and the token needs restore permission. It does not explicitly contrast against sibling alternatives like patch_item_data or update_item for non-restore edits, so it falls just short of a full when/when-not 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context on top: result cap and ordering, the silent-empty failure mode, scope limited to indexed values, and a cost signal ('1 request'). It stops short of auth/rate-limit detail, but that is not needed for a read-only search.

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

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

Three tight sentences, front-loaded with the method and result cap, then the failure precondition, then the sibling routing. No filler and nothing repeated from 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?

An output schema exists, so return-value documentation is unnecessary. Given the four params, full schema coverage, and read-only annotations, the description supplies exactly the missing pieces: scope, cap, precondition, and tag-exclusion routing.

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 'list', 'query', 'includeData' and 'includeItems' are all documented in the schema itself. The description adds no syntax or format guidance beyond the schema (e.g. nothing extra on query length or includeData semantics), so the baseline 3 applies.

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 (full-text BM25 search over a list's searching indexes) plus the result shape (at most 10, best first). An agent can distinguish it from list_items, get_item, and the index-family siblings without opening any 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 excludes tags and routes that case to the sibling: 'Tags aren't searched: filter by tag with list_items.' It also states the precondition for any results at all ('a list without a searching index always finds nothing'), so the agent knows when this tool is useless.

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 say readOnlyHint=true, but the description goes further and matches it precisely: 'Nothing is written', plus it explains the return content (allowed?, which statement decided, all statement evaluations) and discloses cost/rate behavior (1 request plus 1 per looked-up item). This is exactly the extra context annotations cannot provide.

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-loads the core definition, then consequences, then required inputs, then cost, then the cheaper alternative. Four dense sentences with no filler despite covering a complex tool.

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?

Detailed enough for an 11-param, multi-mode tool: it explains outcome, output shape, permissions, request cost, and an alternative approach. An output schema exists, so the description correctly stops short of enumerating return fields.

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% with 11 params, and the description still adds relational meaning beyond it: itemId is tied to update/delete/restore and supplies the old state, while new/patch/merge are framed as alternative write descriptions. Not exhaustive across all 11 params, but meaningfully additive.

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 (dry run / test) and resource (a write against a list's write rules), and distinguishes intent from siblings: this evaluates rules without writing, versus create_item/update_item which actually mutate. The parenthetical clarification of candidate vs saved rules sharpens the scope.

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?

Tells the agent what it needs (describe the write with itemId and new/patch/merge), what permission is required (update on the list), and names an alternative path (JSONPad docs server's check_write_rules) for syntax-only checks with no live data. No explicit 'do not use for X' exclusion, but routing 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds valuable context beyond annotations: rebuild behavior when pointer or valueType changes, refusal conditions for alias (uniqueness/length), guard hiding values, and that omitted fields are preserved. It doesn't explicitly address the destructive nature or reversibility, but the rebuild and guard notes provide significant behavioral insight.

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 extremely concise, packed into a few sentences with no wasted words. Each clause adds a distinct piece of information (partial update, rebuild trigger, alias refusal, guard effect, request count). It is front-loaded with the core behavior and efficiently structured.

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 15 parameters, 80% schema coverage, annotations, and an output schema, the description covers the most critical behavioral nuances: partial update, rebuild cost, alias constraints, and guard effects. It leaves some gaps (e.g., tags replacement, sorting/filtering implications), but overall it provides enough context for an agent to call it correctly without exploring the schema extensively.

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 high (80%), so the schema already documents most parameters well. The description adds a few semantics: omitted fields are left as-is (partial update), and pointer/valueType changes trigger a rebuild. However, it doesn't elaborate on most of the 15 parameters, and the baseline of 3 is appropriate when schema does the heavy lifting.

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 verb (Change) and resource (an index), and specifies partial-update semantics ('fields left out are left as they are'). It is distinguishable from siblings like create_index, delete_index, and rebuild_index. It falls just short of 5 because it doesn't explicitly name a sibling for differentiation, though the operation is unambiguous.

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 usage through behavioral notes (e.g., '1 request', rebuild semantics), but does not explicitly state when to use this tool versus alternatives like rebuild_index or create_index. There are no exclusions or alternative redirections, leaving the agent to infer the right context from the operation type.

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 (destructiveHint=true, idempotentHint=true), the description discloses concrete behavioral traits: guard-index lists refuse a full data replace unless overwriteGuarded is set, the write fails with ITEM_PRECONDITION_FAILED and nothing is written on etag mismatch, and it notes the request cost (1 request, plus 1 the first time to find guard indexes). That is meaningful context the annotations alone don't convey; it stops short only of describing the returned metadata shape, which the output schema covers.

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-loads the core action, then layers the alternative tools, the guard-index refusal, the etag precondition and the request cost in a tight block. Every sentence carries operational information and none is redundant.

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 destructive mutation with annotations and an output schema, the description supplies the missing decision-critical pieces: alternatives, guard-index behavior, etag precondition semantics and cost. Return values are covered by the output schema, so nothing an agent needs to call this 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 coverage is 64%, so the schema already documents data, item, list, tags, ifMatch, returnData and overwriteGuarded. The description adds real meaning on top: it clarifies that data replaces all data, that ifMatch is the read etag gating the write, and that overwriteGuarded overrides guard-index protection. The four bare parameters (version, readonly, activated, description) are only named as metadata fields, so it doesn't fully close the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Change an item's metadata... and, with data, replace all of its data') and enumerates the affected fields. It explicitly names the sibling tools merge_item_data and patch_item_data, so an agent can distinguish this replace-oriented update from partial-data updates without opening any schema.

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

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

Gives explicit routing rules: use merge_item_data or patch_item_data to change only some data, and set overwriteGuarded only when the user means to delete guarded values. It also tells the caller to pass the etag as ifMatch whenever the write is based on a read, covering the when-to-use and when-not conditions.

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 destructive/idempotent/read-write hints, the description adds real substance: partial-update semantics, that a new schema does not retro-validate existing items but governs later writes and restores, that new rules take effect from the next write only after stored tests pass, that rules:null removes them, and that readonly blocks writes to the list, its items, and indexes. All of this is consistent with destructiveHint=true (notably schema and rules changes).

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 semantics before the schema/rules/readonly caveats, and the trailing '1 request.' is a useful cost signal. It is cramped but nearly every clause carries 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?

An output schema exists, so return values need not be described. For a 14-parameter mutation tool the description covers the important behaviors an agent must know before calling: patching, schema scope, rules activation, and readonly. It stops short of stating what happens when the rules tests fail (error shape vs. silent rejection).

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 93%, so the schema already documents list, tags, rules, readonly, and the rest. The description's 'rules: null removes them' largely restates the schema's own null note, and its readonly note mirrors the schema wording. Baseline 3 is appropriate when the schema carries the parameter burden.

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 clause 'Change a list's fields; fields left out are left as they are' gives a specific verb, resource, and patch semantics, which cleanly separates it from update_item and update_index. It does not name a sibling alternative explicitly, so it stops 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?

Usage is implied rather than stated: the agent learns that rules require the stored tests to pass first and that readonly:true blocks writes, but there is no explicit 'use this when...' or 'prefer X instead' guidance across the 31 sibling tools. Conditioning behavior is present; routing advice is not.

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 mark it readOnly, idempotent, and non-destructive, and the description adds substantial behavior beyond them: polling is metered, intervals start at 1s and back off to 10s, the result reports poll count, a failed build surfaces as an error, and a timeout returns timedOut: true with buildStatus "building". This is exactly the context an agent needs to handle the call's cost and outcomes.

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 dense sentences, terminal conditions first, then cost/backoff behavior, then the failure and timeout outcomes. Every clause carries information and 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?

An output schema exists, yet the description still usefully explains the salient return semantics (poll count, timedOut, buildStatus). Combined with full schema coverage and annotations, an agent has everything needed to call and interpret this 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 100%, so list, index, and timeoutSeconds are documented in the schema itself; baseline is 3. The description only alludes to the timeout ('running out of time') without adding format or default detail beyond what the schema already provides.

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 (poll) and resource (index) plus the terminal conditions (ready or failed), which cleanly separates it from rebuild_index, create_index, and list_indexes. An agent can identify the operation 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?

Usage is implied (call it after kicking off an index build to block until completion), but no sibling is named and no explicit when-to-use/when-not guidance is given. A reader must infer that this replaces manual polling via list_indexes.

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