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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that: all-or-nothing rollback on first failure, failure attribution naming the offending command, and the one-line-per-command reply shape. It does not mention auth/permission requirements, so it falls short of a 5.

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

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

Front-loaded with purpose and scale limit, then rules, then return shape. Every sentence carries distinct information (scale, mapping, exclusion, transaction semantics, output), with no repetition of the schema or annotations.

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 batch mutation tool with nested command objects and an existing output schema, the description supplies everything an agent needs: batching threshold, command vocabulary, argument provenance, rollback behavior, and error attribution. Return values are additionally summarized despite the output schema, which is a bonus 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 67% and the description meaningfully augments it: it defines the {type, ...args} shape of commands, enumerates the three valid type values, and points to the single-write tools as the source of truth for the per-command arguments. The actor parameter is left undocumented in both schema and description, keeping this off a 5.

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

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

States a specific verb+resource (apply writes), a hard scale limit (up to 200), and the batching rationale (many known rows in one go instead of one call per row). It explicitly distinguishes itself from the single-row siblings data_add_item / data_update_item / data_move_item by naming them and by naming data_delete_item as the excluded case.

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 (many known rows in one go), an explicit when-not (deletion is not one of the supported command types), and routes the excluded case to the correct alternative, data_delete_item, with the reason (a batch cannot give per-row confirmation). 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: it is a non-UI call, it reports install state, and the catalog is engine-shipped rather than user-created content.

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 resource and scope, and the sibling pointer arrives last where it is most actionable. The phrase 'high-quality' is mild marketing filler that does not help selection, keeping this below 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?

With an output schema present, return values need not be detailed, and the description still flags 'shows install state' as the key payload. For a zero-parameter read tool with full annotation coverage this is close to complete; only the absence of explicit install/preview routing leaves a small 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly adds no parameter narrative.

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 the built-in App Store catalog) and scopes it as engine-shipped apps installable into the user's registry, which separates it from list_apps (registry contents). It also explicitly distinguishes itself from open_app, so an agent can tell the two apart 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 an explicit alternative and the condition that selects it: this tool renders no UI, whereas open_app {app: "app-store"} shows the browsable App Store app. It does not address when to prefer this over install_from_app_store or preview_app_store_entry, so routing guidance 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 readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=true, so the description's additional context about outbound network requests, allowlisted gateways, argument validation, and receipt-per-write adds meaningful behavioral detail. It doesn't contradict annotations. However, it could more explicitly address the destructiveHint implications (e.g., what writes occur and their effects).

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

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

The description is a single dense sentence that front-loads the core action and packs in key behavioral details without waste. It could be slightly more structured for readability, but every clause 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, the description needn't explain return values, but it does mention the reply carries the return value plus a receipt per write, which is helpful. For a tool with 5 parameters, nested objects, and complex annotations, the description covers most essential aspects: function execution, network behavior, argument validation, and failure handling. It could be more complete by addressing the actor parameter or edge cases, but it's largely sufficient.

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

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

Schema description coverage is 20%, so the schema documents only command_id's idempotency purpose. The description adds some meaning by noting that args are checked against declared params and that failures return the declared schema, but it doesn't explain the roles of app, function, or actor parameters beyond what their names imply. With low coverage, more parameter detail would be expected.

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

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

The description clearly states what the tool does: run an app-declared function with data in/data out. It distinguishes itself from siblings like open_app or get_app_html by emphasizing 'no UI needed.' However, it doesn't explicitly name or contrast with any specific sibling tool, leaving some ambiguity about when to choose this over data operations or file operations.

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 for running declared functions without UI, but doesn't explicitly state when to use this vs alternatives like data_add_item or open_app. No exclusions or prerequisites are mentioned, leaving the agent to infer context from the purpose statement alone.

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=false, idempotentHint=true, and destructiveHint=false, so safety and retry behavior are covered structurally. The description adds useful semantics for `group` (an app-defined lane/section) and `fields` (a JSON object shape), but says nothing about persistence, whether the write is immediately visible, or what happens on duplicate calls beyond what the schema's command_id note 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?

Two short sentences, front-loaded with the core action and then the two most ambiguous parameters. Efficient, though the parameter glosses read more like schema notes than a usage-oriented description.

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. But for a 6-parameter mutation tool with nested object fields and low schema coverage, the description omits the relationship to apply_data_writes and the meaning of `position`, leaving the agent to infer ordering and persistence behavior.

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 17% across 6 parameters, so the description carries real weight, and it does explain two key params: `group` as an app-defined lane and `fields` as a JSON object with an example. It leaves `actor`, `position`, and `collection` undefined beyond their names, so it only partially compensates 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 (Add) and resource (item to a collection), which cleanly separates it from data_update_item, data_move_item, and data_delete_item in the sibling list. It does not, however, explicitly name those siblings or contrast itself with them.

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

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

No guidance on when to use this versus data_update_item, data_move_item, or the two-phase apply_data_writes sibling. The presence of apply_data_writes in the sibling set suggests staged writes, but the description never explains whether this call persists immediately or requires a follow-up.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-redundant behavior: events form a contiguous run, are returned oldest-first as whole events (actor, item id, fields), include user edits made in the widget that never pass through the agent, and carry `next_since` for continuation.

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

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

Front-loaded with purpose, and the paragraph packs purpose, mark sources, return shape, and continuation without filler. It is dense enough that the continuation detail sits mid-sentence rather than being broken out, 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 and rich annotations present, the description only needs to add mechanism, and it does: mark provenance, ordering, event contents, and pagination continuation. It omits failure/edge behavior (e.g. what happens if `since` is older than retained history), which is the one gap for a paging read 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 coverage is 67% (`collection` is undocumented in the schema), and the description compensates for the most ambiguous parameter by explaining that `since` accepts several mark formats and what omitting it means. `limit` adds nothing beyond the schema, and `collection` is still only implied.

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+scope: report what changed in a collection after a ledger position the caller holds, including widget-side edits. It distinguishes itself from generic reads by naming the ledger-position mechanism, but it never names the closest sibling (get_data_version), which is the tool an agent would most likely confuse it with.

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 concrete triggering context: pass any mark you hold (write ack's `seq`, data_list's `version`, last call's `next_since`) as `since`, and omit `since` to just learn the current position. It does not state when to prefer get_data_version instead, so one routing question 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the confirmation_required response case and the request_state re-send pattern, which annotations cannot express. It still omits whether confirmation is mandatory or gated by require_confirmation/actor.

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 sentences, front-loaded with the core action and then the edge-case flow. Efficient overall, though the inline quoting of reason:"confirmation_required" is a bit awkward and the field name `note` is used without definition.

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, 6-parameter tool with only 17% schema coverage and a required idempotency key and expected_version, the description is too thin. The output schema removes the need to explain returns, but the parameter surface and the confirmation gating remain undocumented.

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 17% across 6 parameters, so the description carries the burden of compensating and largely fails. It mentions request_state only in the context of the re-send flow, and never explains id, actor, expected_version, or require_confirmation; 'note' is referenced but is not even a declared parameter.

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

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

States a specific verb and resource ('Delete an item permanently'), and the 'permanently' qualifier signals irreversibility. It does not explicitly differentiate itself from siblings like file_delete or delete_app, but the 'item' resource distinguishing it from those is reasonably inferable from the name.

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

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

Provides useful procedural guidance for the confirmation_required flow (show the note, re-send with request_state), which is genuinely actionable. However, it says nothing about when to prefer this over data_update_item or apply_data_writes, and gives no prerequisites or conditions for invoking it in the first place.

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 carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely new behavior: keyset pagination is a live walk where items moved mid-page can be skipped or repeated, and it warns that returned vs total can reveal short deliveries.

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 purpose and the open_app exclusion, then layers pagination and filter semantics efficiently. It is dense and slightly packed with parenthetical asides, but every sentence carries information an agent needs.

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 five parameters, nested match objects, and a live-keyset paging model, the description covers what to expect from a call including page shape and cursor chaining. An output schema exists, so it is not obligated to detail return values further.

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 80%, putting the baseline at 3, and the description exceeds it by defining `match` semantics the schema only illustrates: a bare value means equals, object values are operators {ne, lt, lte, gt, gte, contains, prefix, exists}, and numeric vs lexicographic (ISO date) comparison rules.

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

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

States a specific verb and resource ("Read items in full") plus scope (every field, plus the item id). It distinguishes itself from open_app explicitly, but does not name the closest data siblings (data_changes, data_update_item), so an agent still has to infer boundaries from naming alone.

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 UI needs to open_app, which is a real exclusion. However it gives no conditions for choosing between this and sibling data tools like data_changes or list_data_collections, so the when-to-use is clear only for the UI alternative.

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 non-destructive, idempotent, non-open-world behavior, so the safety profile is covered. The description adds the domain notion of a group/kanban column, but omits concurrency behavior (expected_version), what happens to surrounding items' positions, and whether group can be cleared — context the bare annotations do not supply.

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

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

A single front-loaded sentence with no filler; the example is useful rather than wasteful. It is efficient, though arguably too terse for a six-parameter mutation 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 mutation tool with low schema coverage and an output schema (so returns need not be explained), the description leaves significant gaps: optimistic locking via expected_version, the actor parameter, and idempotency rationale are all unaddressed. It is not sufficient for confident, correct invocation.

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

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

Schema coverage is only 17% (just command_id), so the description must compensate. It loosely characterizes group and position (with the kanban example) but says nothing about actor, expected_version (optimistic-concurrency semantics), or id, leaving four of six parameters undocumented in both description and 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 ("Move an item") and the target dimensions ("another group and/or position"), including a concrete example ("kanban column"). It is clear what the tool does, though it does not distinguish itself from the sibling data_update_item, which plausibly could also change group/position.

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

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

There is no statement of when to use this tool versus alternatives like data_update_item or apply_data_writes, nor any prerequisite or context. Usage must be inferred entirely from the name and the parenthetical example.

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 and idempotentHint, but the description adds genuinely new behavior: shallow-merge semantics, null-to-remove deletion, and optimistic concurrency. It stops short of saying what happens on a version mismatch (error vs retry) or how command_id relates to idempotency, which would complete the picture.

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

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

Two tight sentences, front-loading the merge behavior and deletion rule before the concurrency note. 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?

An output schema exists, so return values need not be described. However, for a destructive mutation with a required idempotency key and version parameter, the description omits conflict/error behavior and does not compensate for the 40% schema coverage on id/actor.

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 40%; command_id and expected_version are described in the schema, but id and actor are undocumented anywhere. The description does add real semantics for the fields parameter (null removes a key), partially compensating, but does not explain expected_version's role in the optimistic-concurrency flow.

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 ('shallow-merge fields into an item') and clarifies scope with the null-removal rule. It distinguishes itself from data_add_item/data_delete_item by implication, but never names a sibling explicitly.

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

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

No guidance on when to use this versus the closely related siblings apply_data_writes or data_changes, which also mutate data. The concurrency and idempotency mechanics are mentioned but no context is given for choosing this tool.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description goes well beyond them: what is deleted vs. kept, that shared/unprovable collections are always kept, that cascade is not undoable, and that it requires a two-step confirmation. This is exactly the behavioral context a destructive tool 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-loads the mode distinction and the irreversibility warning, and every sentence carries load. Slightly heavy: the data mode semantics are restated in both the description and the schema's data field, creating minor redundancy.

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

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

There is no output schema, yet the description tells the agent how to interpret the response (a disposition plan listing what will be deleted and what will be kept and why) and what follow-up call to make. Nothing needed to call this destructive tool safely 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?

With 60% schema coverage, the description usefully expands the data enum (tombstone vs. permanent two-step delete) and explains the request_state round-trip. The actor parameter is left undocumented in both description and schema, and command_id semantics live only in the schema, so it doesn't fully compensate.

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

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

Names a specific verb and resource (delete an app from the registry) and immediately distinguishes the two deletion modes by name. It also names the sibling restore_app as the counterpart, so an agent can place it in the toolset without opening a schema.

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

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

Explicitly states the default (data:"keep" is a tombstone) and when to use the alternative (data:"cascade"). It also prescribes the exact workflow: read the returned disposition plan to the user, then re-send the identical call with request_state — which is precisely the when/how guidance an agent needs.

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: discloses all-or-nothing atomicity ('All edits apply together, or nothing applies'), ordering rules (string edits after ranges, in order), non-overlap constraint on ranges, version anchoring to expected_version, and that the #oma-manifest block is re-read on save. This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the core value proposition, then tight clauses covering each form and the atomicity rule. Dense but every sentence carries information; the parenthetical asides are purposeful rather than 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?

With an output schema present, return values need no explanation, and the description covers everything else an agent needs: form selection, ordering, atomicity, version binding, and the manifest side effect. Nothing material is left to inference.

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?

Description supplies real meaning beyond the 80%-covered schema: it explains that RANGE fields echo get_app's window output (no anchor text travels), that old_string must match exactly once unless replace_all is set, and that offsets target the expected_version document. command_id idempotency is left to the schema.

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

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

Opens with a specific verb+resource and a differentiating constraint: 'Surgical edits to an app WITHOUT round-tripping the whole source.' An agent immediately understands this is a partial-edit tool that stands apart from full-source siblings like save_app.

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?

Clearly states which of the two edit forms to choose (RANGE is 'cheapest', STRING for exact-once matches) and how they compose. It references get_app as the source of offset/hash, but never explicitly says when to prefer this tool over save_app for a given workflow.

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, so the safety profile is covered. The description adds 'Permanently', reinforcing irreversibility beyond the hint, but says nothing about required actor identity, the concurrency role of expected_version, or what happens to the app if the path is wrong.

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

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

A single tight sentence with the key word 'Permanently' front-loaded and zero filler. It is appropriately sized, though borderline under-specified rather than merely concise.

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, but for a destructive, idempotency-keyed mutation with 6 parameters and 17% schema coverage, the description omits the concurrency and identity semantics an agent needs to call it correctly.

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

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

Schema coverage is only 17% (just command_id), and the description adds no meaning for app, path, actor, request_state or expected_version. With 6 params and 5 undocumented in both places, the description fails to 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 (delete), resource (a file), scope (one file, app-stored), and adds 'Permanently'. An agent can distinguish it from delete_app and data_delete_item by the file/app scoping, though no sibling is named explicitly.

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

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

No when-to-use guidance, no prerequisites, and no mention of the adjacent siblings an agent might confuse it with (file_write/file_read for the same files, delete_app for the whole app). Usage must be inferred from the name alone.

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 this a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuinely new behavioral context: results are paginated ('a PAGE of...'), outputs include usage totals, files are opaque, and it 'renders no UI.' That is value beyond the annotations, though nothing is said about limits or failures.

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 and then progressively adds scope, page shape, and the data_list distinction — each clause earns its place. Some density (the parenthetical '(app)', the stacked clauses) leaves minor room for tightening, so not a full 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?

With an output schema present the description needn't explain returns, yet it still outlines the page contents; annotations cover safety and idempotency; all four parameters are covered at 100% schema coverage plus description-level paging semantics. 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 coverage is 100%, so the baseline is 3, but the description adds how the parameters interact: 'limit/cursor page through, prefix narrows.' This explains the paging contract and prefix filtering behavior beyond the per-parameter schema text, lifting it above the baseline.

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 ('List the files an app has stored') and even sketches the returned page shape. It explicitly distinguishes this from the sibling data_list by calling out that these are user files 'separate from its structured data collection.' An agent can tell it apart from data_list and file_read 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?

It gives clear context for when this is the right tool: enumerating opaque user files (attachments, exports) rather than structured data, with paging via limit/cursor and narrowing via prefix. What is missing is an explicit contrast with file_read or data_list by name, so it stops short of full when/when-not/alternatives 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds non-obvious behavior the annotations cannot convey: reads are windows rather than whole-file, the default length fits a result budget (i.e. results may be truncated), and sha256 covers the whole file so reassembly is verifiable.

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

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

A single dense sentence with the core action front-loaded and the reassembly/verification contract at the end. Every clause earns its place, though the parenthetical asides make it slightly harder to parse than necessary.

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

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

An output schema exists, so return values need not be spelled out, yet the description still explains the window/next_offset/sha256 contract that an agent must understand to read a file correctly. Nothing needed to invoke or complete a chunked read 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 75% and the schema documents offset/length defaults, but the description adds meaning beyond it: it explains the relationship between offset/length and the returned window, and names the response fields (data_base64, next_offset) that drive continued reads. This goes beyond the schema's per-parameter text.

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

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

States a specific verb and resource ('Read one file an app has stored') with clear scope ('one file', 'an app has stored'), which separates it from file_list, file_write and get_app. It even cross-references the sibling whose window grammar it reuses, so an agent can place it without opening other 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?

The description implies usage through the windowing model (call with offset/length, follow next_offset until done), but never states when to choose this tool over alternatives such as file_list or get_app, nor any exclusions. Usage is inferable rather than explicit.

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

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

Annotations cover safety (destructive=true, idempotent=true), and the description meaningfully adds version-bump-on-overwrite semantics, the per-call size ceiling, and that files persist and are reusable across chats. It stops short of describing what exactly an overwrite destroys or any auth prerequisites, but it goes 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 compact sentences, purpose front-loaded first, then encoding, versioning, and limits/persistence. No filler and every sentence carries a distinct fact.

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 explained, and the description covers purpose, encoding, versioning, size, and persistence. It lacks explicit pointer to the chunked-write fallback, which is the only real gap for a 6-param 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 the baseline is 3. The description clarifies that data_base64 carries base64-encoded bytes and that overwriting bumps the version (relevant to expected_version), but most parameter meaning still lives 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?

States a specific verb and resource with scope: "Store a file for an app (create or overwrite by path)." An agent immediately knows this is a single-call write. It does not name the sibling chunked-write tools (file_write_begin/chunk/commit), so differentiation is only implicit via the size limit.

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?

"Single-call writes are limited to a few MiB" implies that larger files need the chunked siblings, but this is never stated as a routing rule and the alternatives are not named. No explicit when-to-use vs when-not 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 only cover the safety profile (not read-only, not idempotent, not destructive). The description adds operational context the annotations cannot: the returned upload_id, the ~5 MiB chunk size, the 30-idle-minute expiry, and the 250 MiB per-file ceiling — exactly the lifecycle facts an agent needs to avoid a failed upload.

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, each earning its place: the trigger, the call sequence with return value, and the limits. The scoping condition is front-loaded before the workflow details.

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 an output schema already defines the return shape, the description need not restate it — and it doesn't, instead covering the multi-call lifecycle, chunk sizing, and expiry/ceiling limits. Nothing an agent needs to complete a chunked upload 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?

There is a single parameter with 100% schema description coverage ('the app this file will belong to'), so the schema already carries the parameter meaning. The description adds no parameter-level detail, 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?

States a specific verb and resource ('start a chunked upload for a file') and explicitly scopes it against the sibling file_write ('too big for file_write's single call'). An agent can distinguish this from file_write, file_write_chunk, and file_write_commit 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?

Names the exact condition that selects this tool over file_write (file too large for a single call) and lays out the full workflow sequence with file_write_chunk then file_write_commit. Usage is unambiguous rather than inferred.

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

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

The description usefully discloses ordering and resend semantics (same `seq` is acknowledged rather than double-appended), but this directly conflicts with the annotation idempotentHint=false: an identical re-call with the same seq and data is described as a safe no-op, which is idempotent behavior. Aside from the contradiction, no chunk-size limits or error behavior on out-of-order chunks are given.

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: what it does, how to sequence calls, and why `seq` matters. Front-loaded and 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 the description covers the critical ordering/resend contract for a stateful streaming write. It could still state a maximum chunk size or what happens if `seq` arrives out of order.

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

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

Schema coverage is 67%; `seq` and `data_base64` are already documented in the schema, but the description adds the origin of `upload_id` (from file_write_begin) and reinforces the 0-based ordering contract, adding meaning beyond the raw fields.

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 ('Append the next chunk of bytes ... to an upload') and ties itself explicitly to the sibling that must precede it ('started with file_write_begin'), so an agent can distinguish it from file_write_begin/file_write_commit 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 clear context: it is used only on an upload begun by file_write_begin, chunks must be sent strictly in order and one at a time. It stops short of naming file_write_commit as the terminating step, so the full lifecycle isn't spelled out.

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 destructive, idempotent, and non-read-only, so the safety profile is covered. The description adds genuinely non-obvious behavior: the upload is consumed either way, and a failure forces you back to file_write_begin. It does not mention auth requirements or what the receipt contains, but the consumption/recovery detail is real added value.

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

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

Two tight sentences, front-loaded with what the tool does, followed by the recovery caveat. Every clause carries information; 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?

With an output schema present, return values need no explanation, and the failure/consumption behavior is well disclosed. However, for a 5-parameter mutation tool at 40% schema coverage, the description leaves mime and especially expected_version unexplained, so an agent cannot fully reason about the call from the definition alone.

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 40% (mime, upload_id, and expected_version are undocumented), so the description carries the burden of compensating — and it does not. It gestures at 'path' and 'an upload' implicitly but never names or explains upload_id, mime, or expected_version, the last of which implies optimistic concurrency that an agent must understand.

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 ('Finalize an upload as an app file') plus the create-or-overwrite semantics, and explicitly differentiates itself from the sibling file_write by calling itself 'the chunked equivalent of file_write'. An agent can place it in the write flow 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?

It positions itself relative to file_write (the non-chunked alternative) and names file_write_begin as the restart path on failure. It stops short of explicitly stating the trigger condition ('call after file_write_chunk completes') or when_not_to_use, so it is clear context rather than 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 already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: reads are windowed and verifiable, hash/version are returned to be fed to edit_app/save_app (expected_version, expect_hash). It stops short of stating limits on window size beyond the default budget or any failure modes.

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 first sentence front-loads the window model well, but the middle portion is dense and repetitive: hash is explained twice ('hash lets a range edit confirm it targets exactly the window that was read' vs 'hash, the expect_hash for a range edit of exactly this window'). Several clauses could be tightened without losing meaning.

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 windowing model, the node jump, the manifest slot, and how version/hash feed downstream edits. Only minor gaps remain, such as whether windows can be requested concurrently or any error behavior for out-of-range offsets.

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 80%, so the schema already documents name, node, slot, length and offset; the description mostly restates node/slot semantics and explains the returned window fields (next_offset, total, hash) rather than adding parameter syntax. With high schema coverage this is the expected baseline of 3.

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 ('Read an app's ui source') and immediately qualifies the retrieval model ('as a WINDOW'), which distinguishes it from the sibling get_app_html (rendered html) and get_app_guide (documentation). The slot enum and node behavior are named, so an agent can tell what this tool returns 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?

Gives clear usage context: windowed reads are for transferring large documents in bounded pieces, node jumps the window to a marked element, and slot:"manifest" switches to declaration reading. It does not explicitly say when to prefer get_app_html or get_app_guide instead, so there are no stated exclusions or named 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered without the description. The description adds that this is a static written contract with fixed chapters ('each chapter stands alone'), which is useful context about the return content, but says nothing about size or auth.

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

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

A single front-loaded sentence that lists the guide's contents with zero filler. It is appropriately sized for a one-line documentation lookup, though the enumeration is dense and could have flagged the chapter default.

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, one-optional-param documentation fetch with annotations covering safety and no output schema, the description adequately tells the agent what it will receive. The only minor gap is that the optional 'topic' chapters are not mentioned, but the schema carries them.

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 enum values and the default behavior are already fully documented in the schema. The description does not touch the 'topic' parameter at all, so it adds no meaning beyond what the schema provides. 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?

The description names a specific resource (the authoring contract) and enumerates exactly what it contains: the window.oma API, CSS design tokens, the data model, and a working template. It is clearly a documentation retrieval tool, distinguishable from mutation siblings like save_app or edit_app, though it never names or contrasts a sibling explicitly.

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

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

The phrase 'for creating or editing an app' implies the context in which to reach for this guide, and the schema note 'default basics: the contract + template' hints at entry points. But there is no explicit when-to-use vs an alternative like get_app_html, and no stated preconditions, so usage is only loosely 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=false, idempotentHint=true and destructiveHint=false, so the safety profile is partially covered. The description discloses the returned payload (trust tier, capability grants) but does not explain why a getter is not read-only (the live-pointer side effect noted in the mount param) or any auth requirements, leaving that inference to the schema.

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

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

Two short sentences, no waste, with the internal-only scoping and the redirect to get_app front-loaded so the agent sees the routing advice immediately.

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 enumerated; the description still summarizes the payload (HTML, trust tier, capability grants). The remaining gap is the undocumented required 'name' parameter, which is not covered anywhere.

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

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

Schema coverage is only 50%: 'mount' is documented in the schema but 'name' (the sole required parameter) is undocumented in both places. The description does not compensate by clarifying what 'name' refers to or the effect of the mount flag on returned HTML.

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 ('returns raw app HTML plus its trust tier and capability grants') and explicitly scopes it to the universal loader widget. It also names the sibling it is not ('use get_app to read source'), so an agent can route correctly without opening the schema.

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

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

Explicitly says when-not to call it ('Not useful to call directly') and names the alternative (get_app) for the normal read path. This is exactly the routing guidance an internal tool needs to prevent misuse.

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 and idempotentHint, so safety needs no restating. The description adds genuine value beyond them: precisely what is returned (global seq plus settings/files sub-counters), the cost claim, and the interpretation rule that an unchanged counter means no change occurred.

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 cost/semantics claim. The trailing 'Widgets read it for adaptive polling' is mildly consumer-oriented rather than agent-oriented, but it does convey the intended use pattern without bloat.

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 documented, yet the description still summarizes the return shape and interpretation. With zero params and full annotation coverage of the safety profile, 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?

The tool takes zero parameters, so the baseline is 4; the description correctly spends no words on parameter syntax. There is nothing for it to compensate for.

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: it returns the store's global change counter (seq) plus settings/files sub-counters. The phrase 'the cheapest possible change check' implicitly distinguishes it from heavier change-listing siblings like data_changes, but it never names that alternative, so sibling differentiation is left to inference.

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

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

Usage is only implied: 'An unchanged counter means nothing in the store changed' and 'Widgets read it for adaptive polling' suggest polling-before-expensive-work, but there is no explicit when-to-use versus data_changes or any exclusion. Adequate context, no routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description adds that the catalog is engine-owned and that the tool only describes existence rather than returning effective values, which is genuine behavioral context 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?

Three short clauses front-load the resource and its fields, then immediately disambiguate from oma.pref(). No wasted words.

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

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

Zero-param read-only catalog with an output schema present, so return shape is already covered. The description supplies the one thing an agent needs to not confuse this with value retrieval, plus the field list.

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 baseline is 4. No parameter description is needed and none is misleading.

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 resource (engine-owned catalog of SHARED preferences) with the exact fields it returns (key, type, label, default, options). It also contrasts itself with the sibling-ish mechanism oma.pref(), making clear this tool describes rather than reads values.

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 'Apps read effective values via oma.pref(); this tool only describes what exists,' which tells the agent this is not the value-fetch path. It doesn't enumerate explicit when-not-to-use cases beyond that, but the routing cue to oma.pref() is clear context.

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 (idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine post-call behavior the annotations cannot convey: the installed app behaves like the user's own but receives UI updates from the store rather than local edits. It does not mention permissions or failure modes.

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 action and scope, then the post-install behavior, then the routing hint. Every sentence adds information an agent would otherwise lack.

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 described, and annotations cover safety. The description covers source, effect, and update semantics, though it omits prerequisites such as whether the user needs prior store access or how conflicts with an existing app are handled.

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 both name and command_id are already documented in the schema. The description only points to app_store_list for valid names and adds no format or idempotency-key guidance beyond what the schema states, 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 (Install/update), the resource (a ready-made app from the built-in App Store), and the destination (the user's registry). It also distinguishes itself from the sibling app_store_list by naming it as the discovery tool, so an agent can tell the browse and install operations apart.

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 app_store_list to find what's installable, which is the main pre-call step. It implies but does not state when to prefer update over install or any exclusion conditions, so it stops short of full when/when-not 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 only cover safety (readOnly/idempotent/non-destructive); the description adds substantial non-obvious behavior: metadata-only returns that never include source, that history survives delete_app as a tombstone, and that each checkpoint snapshots BOTH ui and manifest slots which restore_app restores as a pair.

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 return shape, then packs the scoping constraint, numbering, tombstone, and snapshot semantics into tight parenthetical clauses. Every sentence carries a distinct fact 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?

Output schema exists so return-value explanation is optional, yet the description still names the fields. Combined with the tombstone and dual-slot snapshot notes, an agent has everything needed to call this and understand its relationship to restore_app and delete_app.

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

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

The single 'name' parameter has 0% schema description coverage, and the description never explicitly says name is the app identifier it lists checkpoints for — it is only inferable from 'an app's checkpoints'. It does clarify the semantics of the checkpoint number returned (oldest = 1, consumed by restore_app), which is useful but pertains to output, not input.

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 an app's checkpoints') and even gives the return shape {checkpoint, ts, ui_size}. It explicitly distinguishes itself from sibling get_app ('use get_app for the current source'), so an agent can separate 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?

It routes the agent to get_app for current source and names restore_app as the consumer of the checkpoint number, which implicitly defines when this tool is the right choice. It never states an explicit 'use this when' condition or a when-not, so it falls short of 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the meaningful context that the registry is reusable across all chats and that the default scope is the user's openable apps. It doesn't discuss result limits or ordering.

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

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

Two tight sentences: purpose and cross-chat scope first, then the two usage modes. No filler, and the default-scope constraint is front-loaded.

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

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

Adequate for a zero-required-param read tool whose annotations and schema are rich. The default behavior and the three widening levers are all surfaced; only minor gaps like default result count remain.

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% and both enums are documented with defaults (kind default app, visibility default featured+listed). The description restates the lookup/widen behavior but adds no syntax or format detail 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 (List) and resource (UI apps in the registry), and adds scope that distinguishes it from siblings: 'reusable across all chats.' Clearly separates it from get_app (single retrieve) and app_store_list (store catalog).

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 concrete routing: pass name to look one up, or widen with kind/visibility, and the schema notes 'exact app name — the fastest way to answer open my X.' It implies the default-openable-apps behavior but doesn't explicitly name when a sibling like get_app or app_store_list would be preferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds 'Renders no UI', a genuine behavioral trait not expressed in the annotations, though it says nothing about pagination, permissions, or result limits.

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

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

Two sentences, both earning their place: the first defines scope and return shape, the second gives usage triggers. The scope statement is front-loaded and there is no filler.

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

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

For a zero-parameter, read-only listing tool with an output schema present, nothing an agent needs to invoke it correctly is missing. The description covers purpose, when to reach for it, and the no-UI behavior, and it need not explain return values since the 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly adds nothing about inputs and instead describes outputs, which is appropriate here.

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 every data collection') and even enumerates the returned fields (name, item count, last activity), so the agent knows exactly what it gets. It never names or contrasts a sibling such as data_list or list_apps, so differentiation is left to inference from the domain rather than stated.

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

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

The sentence 'Use when unsure where data lives, what boards the user has, or which collection to bind an app to' gives concrete triggering situations, which is stronger than implied usage. However it lists no alternatives or exclusions, so the agent must infer when a different listing tool is preferable.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds genuinely new context: rendering as an interactive widget versus data_list's plain data, and the timing nuance that it works immediately for freshly saved apps. It does not describe loading/failure behavior, but the added context is meaningful.

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 with zero padding; the core purpose and the widget-vs-data_list distinction are front-loaded, and the timing caveat earns its place.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: registry source, widget output, the data_list alternative, and the fresh-app timing edge case.

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%, and the schema already documents both 'app' and 'collection' including the collection default rule, so the description adds only 'by name' at the margin. 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?

States a specific verb and resource ('Open ANY app from the registry by name') and distinguishes the tool from its near-siblings by naming the dedicated open_<name> tools and data_list. An agent can tell what it does without opening the schema.

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

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

Clearly indicates the context in which this tool wins (any registry app, including ones saved moments ago) and names data_list as the no-UI alternative. It stops short of saying when to prefer get_app or the dedicated open_<name> tools explicitly, 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 read-only, idempotent, non-destructive, closed-world behavior, and the description reinforces this with 'nothing is installed' and 'sandboxed'. It also adds real behavioral context the annotations cannot convey: the payload is srcdoc + stub oma + mock snapshot. No rate limits or error behavior are described, but that is minor here.

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

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

One dense sentence plus two short qualifiers, with the important context ('Internal:', 'Read-only', 'Not useful to call directly') front-loaded and easy to scan. Slightly jargon-heavy (srcdoc, stub oma) but not padded.

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 prose, and the single-parameter surface is fully covered by the schema. For an internal read-only tool the description supplies enough to understand what it does and to avoid misusing 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 coverage is 100% and the single parameter ('name') is already documented in the schema with a pointer to app_store_list; the description adds no syntax, format, or naming detail beyond that. 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?

The description names a specific verb (returns) and enumerates the exact payload: an entry's ui, manifest, and mock-data fixtures, plus the end goal (render a live sandboxed preview card). It clearly is not install_from_app_store or get_app, though it never explicitly names a sibling to compare against.

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

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

It gives a clear negative directive ('Not useful to call directly') and explains why (internal, consumed by the App Store app to render a preview), which effectively tells an agent to stay away. It does not, however, state the positive condition under which a direct call is warranted.

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: it discloses that the operation is atomic, that it preserves every other manifest key, that it creates a new version, and that the write is OCC-guarded with history retained. This is rich behavioral context an agent cannot get from idempotentHint/destructiveHint alone.

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 packs the preconditions, no-op case, and refusal case into a compact span with no filler. The dense jargon-laden clause structure is slightly heavy, but every clause carries meaning.

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, and the description fully covers the state change, side effects, and edge cases an agent needs. Complete for this lifecycle verb.

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 both parameters are already documented in the schema (name must reference an existing visual app, command_id is an idempotency key). The description adds no parameter-level detail beyond that, 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 ('upgrade a kind:"visual" app to a full app') with a concrete mechanism ('flips `kind` in the stored manifest'). It clearly distinguishes itself from siblings like save_app, edit_app, and list_apps by naming the exact state transition it performs.

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 covers when it applies (visual app), when it is a no-op ('Already an app is a no-op'), when it refuses ('downgrades are refused'), and names the correct alternative for the reverse case (save_app with the manifest). 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?

Adds real context beyond annotations: the operation is non-destructive because history is preserved and the agent can roll forward again, and the restore creates a new current version rather than mutating history. Annotations already declare destructiveHint=false and idempotentHint=true, so the description's main added value is explaining the mechanism and reversibility, though it doesn't mention permissions or effects on associated app data.

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: purpose/mechanism first, then the trigger, then the prerequisite and follow-up. Every clause carries information and nothing 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 a mutation tool with no output schema, the description covers the mechanism, reversibility, trigger, prerequisite, and next step. It is nearly complete, though it says nothing about whether app data (versus HTML) is affected or any permission requirements.

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

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

Schema coverage is 67%: 'checkpoint' and 'command_id' are already documented in the schema, and the description's 'Get the checkpoint number from list_app_checkpoints' largely repeats the schema note. The 'name' parameter is undocumented in both places. With mid-level coverage, the description neither compensates nor detracts, so baseline 3 fits.

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 ('roll an app back') and resource ('one of its earlier checkpoints'), and immediately explains the mechanism (re-saves that checkpoint's HTML as a NEW current one). This clearly separates it from siblings like save_app, edit_app, and promote_app.

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 names the triggering condition ('Use when a newer edit broke the UI'), the prerequisite source ('Get the checkpoint number from list_app_checkpoints'), and the follow-up action ('after restoring, open_app to view it'). The when-to-use and routing are fully specified.

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=false, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: every save snapshots both slots as one new version with history kept, and manifest: null clears the declaration. It doesn't restate annotation content, which is a plus.

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

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

Front-loaded with purpose, then slot semantics, then the critical next action (open_app). Dense but each clause carries information. Em-dash nesting makes it slightly heavy to parse, but nothing 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?

An output schema exists, so return values need not be explained, and the description covers the mutation semantics, versioning, and follow-up action. It omits mention of expected_version's overwrite requirement and command_id idempotency, though both are documented in 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 100%, so the baseline is 3, but the description adds real meaning on top: the omit-to-keep vs null-to-clear semantics for each slot, and the requirement that creating needs ui. The contract pointer (get_app_guide) for ui/manifest contents is useful context the schema does not carry.

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 or update a UI app in the persistent registry,' which immediately tells the agent this is the write path for app definitions. It further clarifies the two-slot model (ui + manifest). It does not, however, explicitly differentiate itself from the sibling edit_app, leaving the create-vs-edit boundary to inference.

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

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

It gives a clear operational rule: 'Creating needs ui' and 'After saving, open it IMMEDIATELY with open_app,' which routes the agent to the correct follow-up tool. It also explains omitted-slot behavior on update. It stops short of naming alternatives (e.g., when to prefer edit_app or restore_app over this tool).

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds real context beyond them: privileged status, exclusivity for reserved keys, and upsert (overwrite) semantics. It does not describe permissions/auth prerequisites for a 'privileged' writer, leaving one meaningful gap.

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

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

Two sentences, zero filler, and the differentiating facts (privileged, reserved keys, exclusivity) are front-loaded before the generic upsert statement.

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 declaring safety/idempotency and a full output schema plus 100% parameter documentation, the description carries little remaining burden and covers purpose, exclusivity, and mutation semantics adequately. The only shortfall is not flagging the privileged access requirement it asserts.

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 key, value, and command_id in significant detail (accepted value forms, refusal of unknown values, idempotency). The description adds only the generic 'one key/value' framing, which is the expected baseline when the schema carries the 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?

States a specific verb and resource ('Upserts one key/value in the settings collection') and adds a precise scope constraint ('reserved settings keys security:* / policy:*'). It also distinguishes itself from siblings by noting the generic data_* tools refuse reserved keys, so an agent can route 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?

The description gives a clear selection condition (reserved security:*/policy:* keys) and rules out the alternative family ('the generic data_* tools refuse reserved keys'), which functions as a when-not. It stops short of an explicit directive naming the tool to use for non-reserved writes, so the guidance is strong but not fully enumerated.

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