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 two traits annotations cannot express: that the ledger retains the last contents (audit/soft-delete behavior) and the two-step confirmation handshake with request_state. It still omits permission requirements and the effect of a stale expected_version.

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 action and then the two non-obvious behaviors. No filler, 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?

An output schema exists so return shapes need not be described, and annotations cover the safety profile. The description covers the highest-risk flow (confirmation/request_state) well, but a destructive mutation with an expected_version parameter should say more about version conflicts and actor semantics.

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 33%, so the description must carry more of the burden. It does add real meaning for request_state (attach it on the retry), but leaves id, actor, and expected_version entirely unexplained, so the compensation is only partial.

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

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

States a specific verb and resource ('Delete an item'), which cleanly separates it from data_update_item, data_move_item, and data_add_item in the sibling list. It stops short of naming an alternative or scoping what an 'item' is, so it is clear but not maximally differentiating.

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 real procedural rule for the confirmation_required path (show the user the `note`, then re-send with request_state), which is genuine usage guidance. However, it says nothing about when to choose this tool over siblings or what preconditions (collection membership, version) must hold, so usage is only partially covered.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond annotations – no mention of the collection-scoped refusal, version conflicts, or side effects, which the schema handles instead.

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 wasted words and a helpful parenthetical example. However, given a 7-parameter mutation tool, this level of brevity leaves too much unsaid rather than being optimally sized.

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 7 parameters, 2 required, 29% schema coverage, and a mutation operation, the description is far too thin. An output schema exists so return values needn't be described, but the description should still convey concurrency (expected_version) and actor semantics that it omits.

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 29%, so the description must compensate, but it only hints at 'group' and 'position' via the kanban example. Critical parameters like expected_version, actor, and id receive no clarification in the description, leaving the coverage gap unaddressed.

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

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

States a specific verb (move) and resource (item) plus the target dimensions (group and/or position) with a clarifying example (kanban column). It does not name or distinguish itself from siblings like data_update_item, so it stops short of a 5.

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

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

The description gives no when-to-use context, prerequisites, or alternatives such as data_update_item or data_add_item. An agent must infer that this is for repositioning/regrouping rather than general field edits.

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

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

Annotations declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: shallow-merge semantics, the null-to-remove convention, and that writes use optimistic concurrency (implying expected_version conflicts). It stops short of describing conflict failure behavior or auth requirements.

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

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

Two compact sentences, front-loaded with the core operation and its most surprising behavior (null deletes). No filler, every clause carries information.

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

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

With an output schema present, return values need not be explained, and annotations cover safety. The description supplies the merge/concurrency behavior an agent needs, but omits guidance on tool selection and leaves the 'actor' parameter 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 coverage is 50%: collection, command_id, and expected_version are already documented in the schema. The description contributes meaning for 'fields' (null removes a key) and hints at expected_version via optimistic concurrency, but leaves 'id' and 'actor' entirely unexplained. Roughly baseline for partial coverage.

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

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

States a specific verb and resource ('shallow-merge fields into an item') and even clarifies the semantics of the merge, which implicitly distinguishes it from full-replace or bulk-write siblings like apply_data_writes. It does not, however, explicitly name or contrast against any sibling tool, so it stops short of a 5.

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

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

There is no guidance on when to use this versus alternatives such as apply_data_writes, data_add_item, or data_move_item, nor any stated preconditions beyond what the schema implies. The merge/null semantics are useful but describe mechanics, not selection criteria.

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 annotations declare destructiveHint=true and idempotentHint=true, but the description adds the non-obvious and decision-critical fact that data, files and history are KEPT and that the action is reversible via restore_app. That materially softens the bare 'destructive' hint and is exactly the kind of context annotations cannot carry.

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

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

Three short sentences, front-loaded with the action and followed by the retention and reversibility facts. The final sentence is slightly awkward ('is the user's, in the settings app') but still earns its place by preventing misuse.

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 no-output-schema mutation tool, the description covers reversibility, data retention, and the correct owner of permanent erasure. Auth/permission requirements and return behavior are not addressed, but nothing else an agent needs to call it 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?

Schema coverage is only 33%: only command_id carries a description ('idempotency key — generate a fresh uuid per action'). The description says nothing about name or actor, so it does not compensate for the undocumented parameters even though actor's enum makes it largely self-explanatory.

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 app from the registry') and immediately bounds the scope: only the registry entry goes, not the underlying data. The closing sentence implicitly distinguishes it from the sibling purge_app, which is the tool that erases data.

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 restore_app as the reversal path and explicitly rules out the data-erasure use case, telling the agent that permanent deletion is a user action in the settings app rather than a call it should make. It stops just short of naming purge_app as the sibling alternative, so the 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?

Adds real behavior beyond annotations: atomic apply ('All edits apply together, or nothing applies'), non-overlap and ordering constraints, version-pinned offsets, and that manifest/skill slots are preserved. This complements the idempotentHint/non-destructive annotations with mutation-specific rules an agent needs.

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

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

Front-loaded with purpose and the two forms, then constraints, with each sentence carrying information. It is dense and slightly packed, but nothing is redundant or wasteful.

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 non-obvious multi-form edit tool, it covers atomicity, ordering, version pinning, and preserved slots, and an output schema exists so return values need not be described. Nothing an agent needs to call it correctly is missing.

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

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

Goes well beyond the 80%-covered schema by defining the RANGE vs STRING form semantics, what offset/length/expect_hash are read from (get_app's window), that offsets address the expected_version document, and that string edits apply after ranges in order. That is substantive meaning not derivable from the schema alone.

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

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

States a specific verb (edit) and resource (app source) plus the mechanism ('surgical edits ... WITHOUT round-tripping the whole source'), which distinguishes it from a full-save sibling like save_app. An agent can tell what this does and what it avoids 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?

Explains when each edit form applies: RANGE is 'cheapest' and echoes get_app's offset/returned/hash, STRING is for an exact-once match with optional replace_all. It also notes mixing and ordering. It stops short of explicitly contrasting with save_app for whole-file rewrites, so it is clear context rather than 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 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 already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description adds genuinely new behavioral context beyond them: overwriting bumps the path's version, files are capped at a few MiB, and files persist across chats. It stops short of describing error behavior on size violations or what happens on version conflicts.

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

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

Four short sentences, zero filler, with the core verb/resource and overwrite semantics front-loaded before secondary details like encoding, size cap, and persistence.

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 the mutation semantics, size limit, and persistence that an agent needs. It could go one step further on conflict handling for expected_version, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, and the baseline is 3. The description restates data_base64's encoding and gestures at versioning via 'bumps its version', but does not explain expected_version's optimistic-concurrency semantics or command_id's idempotency role beyond what the schema says.

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 ('Store a file for an app') plus the create-or-overwrite scope in parentheses. An agent can immediately distinguish it from siblings like file_read, file_list, and file_delete.

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 parenthetical 'create or overwrite by path' and the note that files 'persist and are the app's own, reusable across chats' imply when this tool is appropriate. However, no alternative is named (e.g. when to prefer file_delete or a data_* tool) and there is no explicit 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 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 carry the safety profile (idempotentHint, destructiveHint, readOnlyHint), so the bar is lower; the description still adds useful context by flagging the tool as internal and not for direct use. It does not explain the state-recording side effect implied by readOnlyHint=false and the 'mount' parameter, which would have earned 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?

Two short sentences with zero waste; the purpose is front-loaded and the routing guidance follows 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 no explanation, and the description covers purpose and the correct alternative. The only gap is the undocumented 'name' parameter and the unexplained non-read-only behavior tied to 'mount'.

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 50%: 'mount' is well documented in the schema, but 'name' has no description anywhere, and the description text adds no parameter meaning at all — it only describes return content. With a coverage gap, the description should have compensated and does not.

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 gives a specific verb and resource ('returns raw app HTML plus its trust tier and capability grants') and explicitly distinguishes itself from the sibling get_app by declaring the tool internal and not meant for direct calls.

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

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

It states an explicit when-not condition ('Not useful to call directly') and names the alternative to use instead ('use get_app to read source'), leaving nothing to inference.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds important provenance and trust context: the notes are author-written, returned as reference with the author named, and are not instructions from the user. It does not cover error behavior or output format.

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 front-loaded and free of filler. The first defines the content and its scope; the second clarifies return provenance and a critical interpretation warning.

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

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

For a simple read tool with full annotation coverage and no output schema, the description is complete enough. It states what is returned, how it is attributed, and the essential caveat that the notes are not user instructions.

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 single parameter is fully documented in the schema. The description adds no parameter-specific meaning, so the baseline of 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?

The description clearly identifies the resource as an app's author-written usage notes and lists their contents: workflow, placement, and scheduling. It does not explicitly differentiate from siblings like get_app_guide or get_app, so a 4 rather than a 5.

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

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

The description provides no explicit when-to-use conditions or alternatives to other app-related tools. It only cautions how to interpret the returned notes, not when to select this tool over get_app_guide or get_app.

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. The description adds genuinely new context: the probe is polled by the runtime, returns a global seq plus settings/files sub-counters, and is not meant to be invoked by the model — all useful behavioral framing 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?

One dense sentence with no filler, and the 'Internal' qualifier is front-loaded. The important exclusion ('Not for the model') is buried at the end, but the sentence still reads efficiently.

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

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

An output schema exists, so return values need no explanation, and the rich annotations cover safety. The description supplies the remaining needed context — what the counters represent and who is expected to poll them — leaving little for an agent to guess.

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

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

Schema description coverage is 100% and the single 'collection' parameter is already documented as narrowing the seq. The description's mention of a global counter plus sub-counters gives some context on what is being scoped, but adds no syntax or semantics beyond the schema. 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 resource and mechanism: the store's global change counter (seq) plus settings/files sub-counters, exposed as a change probe. The 'Internal... widget runtime' framing clearly separates it from the sibling data_* and file_* tools, though the verb itself is left implicit.

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 exclusion — 'Not for the model' — plus the intended consumer pattern ('polled to decide whether to refetch'), so an agent knows it is not the tool for user-facing data checks. It does not, however, name the sibling an agent should use instead (e.g. data_changes).

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 declare it as non-read-only, idempotent and non-destructive; the description adds genuinely new behavioral context: install doubles as update, the app then behaves like a user-owned app, and its UI updates come from newer store versions rather than local edits. Minor gap: it doesn't state what happens on name collision beyond the parenthetical 'or update'.

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, zero filler, with the core action and its update semantics front-loaded before the pointer to app_store_list. Every sentence earns its place.

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

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

An output schema exists so return values need not be explained, and the annotations cover the safety profile. What remains — discovery via app_store_list and the post-install update model — is fully covered, leaving nothing an agent needs in order to invoke this correctly.

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

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

Schema coverage is 100% and both parameters (name, command_id idempotency key) are documented in the schema itself. The description adds no syntax, format or constraint detail beyond what the schema already provides, 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+resource (install/update a ready-made App Store app into the user's registry) and immediately differentiates from the user's own apps by explaining that installed store apps update from the store rather than from edits. An agent can distinguish it from save_app/edit_app 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 — use app_store_list to discover available entries, and install-from-store is the path for ready-made apps rather than authoring your own. It lacks an explicit exclusion (e.g., 'use save_app to create your own app'), 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 already declare readOnly/idempotent/non-destructive, yet the description adds genuinely non-obvious behavior: history survives delete_app (tombstone), checkpoint 1 is oldest, and each checkpoint snapshots all slots (ui, manifest, skill) restored together. These are behavioral facts an agent could not derive from annotations.

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

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

Four dense sentences, front-loaded with the core action and response shape. Every clause carries weight (shape, metadata-only, ordering, tombstone, snapshot semantics), though the em-dash parentheticals make it slightly cramped. 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?

Output schema exists so return fields needn't be explained, yet the description still supplies the checkpoint-ordering semantics needed to call restore_app correctly. Safety profile is covered by annotations and the metadata-vs-source distinction is fully stated. Nothing required for correct invocation 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?

Only one parameter ('name') exists and schema coverage is 0%, so the description should compensate, but it only implies name via 'an app's checkpoints'. The rich detail it provides is about return-field semantics (checkpoint numbering), not the input parameter. Adequate but not a full compensation.

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

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

States a specific verb+resource ('List an app's checkpoints') and even declares the response shape ({checkpoint, ts, ui_size}). It distinguishes itself from the sibling get_app by framing this as metadata-only versus current source. An agent can tell exactly what this 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?

Names the alternative tool and the condition that selects it ('metadata only, NEVER the source ... use get_app for the current source'). It also routes to restore_app by explaining which checkpoint number that sibling consumes. This is explicit cross-tool routing, not 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes the registry/chats scope ('reusable across all chats'), which is genuinely useful context, but says nothing about result size, ordering, or pagination.

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 sentence, front-loaded with the resource and scope, with the lookup hint trailing. Nothing is wasted and no sentence is padding.

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

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

For a read-only list tool with no output schema and full annotation coverage, the description supplies enough to select and invoke it correctly. The only gap is that it doesn't indicate what the listing returns or its shape, which is minor given the annotations.

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

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

Schema description coverage is 100% and the single optional param is already documented in the schema, so the baseline is 3. The description reinforces the lookup use case for 'name' but adds no format or matching details beyond what the schema already says.

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

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

The description states a specific verb+resource ('List UI apps in the registry') and adds scope context ('reusable across all chats') that separates it from app_store_list, which lists store entries rather than installed apps. It stops short of explicitly naming sibling alternatives, so differentiation is inferential rather than stated.

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

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

It hints at the lookup pattern ('pass name to look one up') for the optional name param, but gives no explicit when-to-use guidance, no exclusions, and does not name alternatives such as get_app or app_store_list. Usage is implied rather than directed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, and the description adds a genuinely new trait: 'Renders no UI.' That is useful context about side effects on the interface that annotations do not convey. It stops short of describing sizing or volume of returned collections.

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: what it returns first, then when to reach for it. Every clause carries information and nothing is 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-value detail is already covered and the description need not (and mostly does not) duplicate it. For a zero-parameter read tool with full annotation coverage, the definition is essentially complete; only the relationship to sibling listing tools like data_list is left unstated.

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 nothing for the description to disambiguate and the baseline is 4. The description correctly implies an unfiltered full listing rather than a parameterized query.

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 gives a specific verb and resource ('List every data collection') and even previews the returned fields (name, item count, last activity). It is clear on its own, but it never names or contrasts with the close sibling data_list, so an agent must infer the boundary between 'collections' and collection items.

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?

Explicit when-to-use triggers are given: 'unsure where data lives, what boards the user has, or which collection to bind an app to.' That covers discovery and binding scenarios well, though no when-not or named alternative (e.g., data_list) is offered.

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

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

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 cover read-only/idempotent/non-destructive, but the description adds real value beyond them: the sandboxed srcdoc + stub oma + mock snapshot rendering model and the explicit 'nothing is installed' assurance. It does not discuss payload size or failure behavior.

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

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

A single dense but front-loaded sentence that leads with 'Internal' and the return payload. The parentheticals (srcdoc + stub oma + mock snapshot) are slightly heavy but each 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?

With an output schema present, the description needn't document return values, and it still sketches the payload shape. Combined with full annotation coverage and 100% param coverage, an agent has what it needs to decide not to call it directly.

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 name and locale are already fully documented, including the enum and default. The description adds no parameter-level meaning, which is the expected baseline when the schema does the work.

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 (returns) plus a precise resource (an App Store entry's ui, manifest and mock-data fixtures), and frames it as an internal preview payload. This clearly separates it from siblings like install_from_app_store and get_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?

The closing sentence 'Not useful to call directly' is an explicit when-not signal that most definitions lack, and 'Internal' clarifies the intended caller. No alternative tool is named for agents that do want store data, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description's job is to add detail. It does: deletion is permanent, it affects only the app's exclusive data, and shared or 'unprovable' collections are deliberately preserved. The plan-then-apply flow is genuinely useful behavioral context, though it doesn't cover auth/permission requirements or reversibility beyond 'permanently'.

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 scope restriction and destructive scope before the plan/apply mechanics. Every clause carries information; no filler.

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

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

For a destructive, no-output-schema tool with 4 params, the description covers the key risks: permanence, the two-call pattern, and what data is spared. It omits permission/auth prerequisites and any hint about what the returned plan contains, which slightly weakens completeness.

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 50%: command_id and request_state carry their own descriptions, while name and actor are bare. The description clarifies the role of request_state within the plan workflow, but adds nothing about command_id, name, or actor semantics. Baseline 3 is appropriate given the partial schema coverage.

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

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

States a specific verb ('deletes') plus resource ('an app AND the data only it used') and scoping ('Settings app only'), which separates it from the sibling delete_app that presumably removes the app alone. 'Permanently' also signals irreversible scope, so an agent can choose 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?

The description establishes context ('Settings app only') and explains the two-phase workflow: first call returns a plan, the re-sent call with request_state executes it. It never explicitly names delete_app as the alternative or states when purge is preferable, so it stops short of a full when/when-not statement.

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

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

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?

Substantially exceeds the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses version-snapshot behavior ('Every save snapshots all slots as one new version (history kept)'), null-clears semantics, the no-embedded-manifest constraint plus CDN allowlist fallback, and the expected_version precondition for overwrites. This is exactly the write/auth/state context annotations alone 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 purpose and then the slot semantics, with no filler sentences. The parentheticals and mid-sentence constraint packing make it dense, but each clause carries actionable 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?

Given an output schema exists and annotations cover the safety profile, the description supplies everything else an agent needs: slot semantics, creation vs. update rules, versioning/rollback context, and the required post-save open_app step. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: which slots exist conceptually, that 'Creating needs ui', and the HTML contract dependency on get_app_guide with the manifest-block prohibition. It still doesn't elaborate on command_id or expected_version beyond what the schema text already says.

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

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

States a specific verb+resource and scope: 'Create or update a UI app in the persistent registry,' and enumerates the three slots it writes (ui, manifest, skill). It does not, however, differentiate itself from the sibling edit_app, leaving ambiguity about why an agent would choose one over the other.

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

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

Gives explicit conditions ('Creating needs ui', 'an omitted slot keeps its current value' on update) and a mandated follow-up action ('After saving, open it IMMEDIATELY with open_app'), which is real routing guidance. It stops short of stating when to prefer save_app over edit_app or purge_app, so no exclusion guidance is present.

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

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

Annotations already declare non-read-only, non-destructive, closed-world behavior, so the bar is lowered. The description adds real context beyond the annotations: the user watches the effect happen, and the return differs by mode (screen after a press, the tool's answer after a call).

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

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

Front-loads the core action, then parenthetically fills in parameters and return behavior in roughly two dense sentences with no filler. Slightly heavy on asides but every clause carries information.

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

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

For a 7-parameter, zero-required tool with a nested input object and no output schema, the description usefully explains both the input source (screen_read) and what comes back for each mode. It stops short of covering failure/error behavior or ambiguity when both ref and label are supplied.

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 adds only relational meaning (ref originates from screen_read, label is a fallback) that largely duplicates the schema's own wording, without clarifying interactions between app/ref/label/value.

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

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

States a concrete verb and resource ('do what the user would do in the app they have open') and enumerates the three action modes: press a control, fill/select a value, or call the app's own tool. This clearly separates it from screen_read (which yields refs) and from pure data tools.

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

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

Gives explicit operating context: use a ref from screen_read or the control's visible label, and the default action mapping for text inputs vs dropdowns vs everything else. It also disambiguates intent ('"Show me Thursday" is an action in the app, not a data query'), though it never explicitly contrasts itself with siblings like call_function or screen_poll.

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 adds one genuinely useful behavioral trait beyond the annotations: this is a long poll, so it blocks/waits rather than returning immediately. Annotations already declare non-destructive and closed-world (openWorldHint=false), so the safety profile is covered, but nothing is said about timeout, retry, or payload shape.

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 discharges the internal/app-only qualifier first and wastes no words. Its brevity is efficient rather than padded, though the size is small relative to the tool's actual complexity.

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

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

For a tool with 8 parameters, a nested object, and no output schema, the description is far too thin; the job/status field semantics are undocumented anywhere. Being internal lowers the bar somewhat, but an agent still lacks what it needs to interpret or drive the poll 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?

Eight parameters are documented at 0% schema coverage, and the description explains none of them. 'The open app's' faintly gestures at the app/session scope, but the opaque fields (born, done, touched, ping, display, visible) and the nested 'done' object are left entirely unexplained.

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 gives a verb-ish action ('long poll') and a resource ('screen jobs') scoped to 'the open app', which separates it from siblings like screen_read and screen_act. However, 'screen jobs' is never defined, so an agent cannot form a concrete picture of what is being polled or returned.

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 parenthetical 'Internal (app-only)' signals who should invoke it and implies external callers should stay away, which is meaningful routing guidance. But it names no alternative and states no positive condition for use, so the when-to-use vs siblings is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the no-side-effect profile is covered. The description usefully adds what the read returns, including actionable control refs, but says nothing about staleness, whether the screen must be foregrounded, or how refs relate to screen_act — modest added value against an already-covered safety profile.

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 front-loads the return payload and closes with the usage trigger; the quoted examples earn their space. Slightly run-on, but there is no filler sentence to cut.

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

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

With no output schema, the description carries return-value explanation and does so reasonably well by listing text, controls with refs, and app tools. For a 1-parameter read tool this is close to complete, though it omits how refs are consumed downstream and whether the read is scoped to a single foreground 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?

Only one optional parameter and schema description coverage is 100%, so the schema already explains the app selector and its default. The description's mention of "the app they have open" merely echoes the schema default rather than adding format or resolution semantics, so the baseline 3 applies.

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

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

States a specific verb and resource — reading what is currently on the user's screen — and enumerates the payload (text, every control with a ref like r3, the app's own tools). That content profile implicitly separates it from get_app_html and screen_act, but no sibling is named outright, so it falls just short of the top band.

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

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

Gives a clear trigger with concrete user utterances ("what's on Thursday?", "that one"), which is exactly the deictic case an agent needs to recognize. It offers no when-not guidance and does not route to screen_act for acting or get_app_html for markup, so no exclusions are present.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the reserved-key exclusivity mechanism (only this tool can write these keys), which is useful context, but it does not say whether an existing policy value is overwritten or what authorization is required.

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

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

Two tight sentences with the scope restriction ('Settings app only') front-loaded, followed immediately by the key namespace and the sibling-alternative 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?

With an output schema present, return values need no explanation, and the description covers scope, key namespace, value semantics and idempotency (via schema/annotations). Only the overwrite behavior on an existing policy remains unstated, which is a minor gap.

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

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

Schema description coverage is 100%, so key, value and command_id are fully documented in the schema. The description only restates that the key is reserved and that unknown values are refused, adding no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('writes one reserved settings key'), gives the exact key namespaces (security:* / policy:*), and scopes it to the Settings app. It is clearly distinguishable from the data_* siblings, which it explicitly contrasts 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?

Names the condition that selects this tool (reserved security/policy keys) and the alternative that fails ('The generic data_* tools refuse reserved keys'), which is strong routing guidance. It does not explicitly state when NOT to use it or what prerequisites/authorization apply.

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