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

Beyond the annotations (readOnlyHint, openWorldHint), the description discloses that the tool returns metadata only, not source, which is a deliberate design to keep context small. It also uncovers tombstone semantics (survives delete_app) and that each checkpoint snapshots both UI and manifest, providing restoration context.

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

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

The description is three sentences, each adding distinct value: listing action, checkpoint numbering and restore usage, and tombstone persistence. No fluff, every sentence earns its place, and key details are front-loaded.

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

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

For a simple read-only list tool with a single parameter and an output schema, the description covers all necessary context: what it returns, what it doesn't return, how to use the results with restore_app, and edge-case behavior (deleted apps). No missing critical information.

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

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

The schema only has a 'name' string with no description. The description's phrase 'an app's checkpoints' clearly implies 'name' is the app identifier, but it doesn't explicitly state that the parameter is the app name or define any format. Since schema coverage is 0%, the description provides just enough context but could be more explicit about the parameter's role.

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 ('List') and resource ('an app's checkpoints') with an explicit output shape ({checkpoint, ts, ui_size}). It clearly distinguishes itself from get_app by saying 'metadata only, NEVER the source' and from restore_app by noting that checkpoint numbers are used by restore_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 description explicitly tells when to use this tool: 'use get_app for the current source' for retrieving source, implying use app_history when you need checkpoint metadata. It also establishes a relationship with restore_app ('restore_app takes that number') and notes that history survives delete_app, which is useful for deleted apps.

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 safety is covered. The description adds useful context about what the tool returns (raw HTML, trust tier, capability grants) and marks it as internal, which helps the agent understand its intended scope.

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 concise sentences with no wasted words. The core behavior is front-loaded, and the routing guidance to get_app is placed second.

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

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

For a simple one-parameter, read-only tool with an output schema, the description is complete. It covers purpose, internal status, return contents, and the appropriate alternative, leaving nothing critical missing.

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

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

The single required parameter 'name' has no schema description, and the description does not explicitly define it as the app name. However, the tool name and the phrase 'app HTML' make it inferable that 'name' identifies the target app, providing just enough semantic grounding.

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

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

The description states a specific action and resource: it returns raw app HTML plus trust tier and capability grants for the universal loader widget. It also explicitly distinguishes itself from get_app, making the tool's purpose unambiguous.

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

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

The description explicitly says this tool is 'Not useful to call directly' and tells the agent to 'use get_app to read source.' This provides clear when-not-to-use guidance and names the correct 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?

The description adds behavioral context beyond the annotations: it notes that the tool shows install state and renders no UI. This is consistent with readOnlyHint=true and provides useful additional insight into what the agent should expect from the tool's output and side 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 two sentences, with the primary purpose front-loaded in the first phrase. Every word contributes to meaning, and there is no redundancy or filler.

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

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

For a zero-parameter read-only listing tool with an output schema and clear annotations, the description provides everything needed: what the tool lists, the install-state information, the no-UI behavior, and a pointer to the alternative for UI. No gaps remain.

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

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

The tool has zero parameters, so the description doesn't need to clarify parameter meanings. It adds value by describing the content of the list (ready-made, high-quality apps shipped with the engine) which helps the agent understand what the tool returns. Baseline for zero params is 4, and the description meets it.

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

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

The description clearly states the tool's function with a specific verb ('browse') and resource ('built-in App Store'), and distinguishes itself from sibling open_app by explicitly noting that it renders no UI. This makes its purpose unambiguous and differentiated.

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 explicitly tells the agent when to use this tool: to browse the built-in App Store programmatically. It also provides an explicit alternative, open_app {app: "app-store"}, for when a UI is desired, making the usage boundaries clear.

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

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

Annotations already declare readOnlyHint=true. The description adds that 'nothing is installed' and describes the sandboxed nature with 'mock-data fixtures' and 'LIVE sandboxed preview card,' which goes beyond the annotation. No contradiction.

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

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

Two sentences, front-loaded with 'Internal,' and each sentence conveys a distinct piece of information: what it returns, why it exists, and that it's safe and not for direct use.

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

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

The tool has a single parameter, an output schema, and annotations. The description covers the purpose, internal nature, side-effect-free behavior, and sandboxed output. Nothing critical is missing.

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

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

The only parameter 'name' is documented in the schema with reference to app_store_list, so coverage is 100%. The description itself doesn't add any parameter detail, so baseline 3 applies.

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

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

The description uses 'returns' as the verb and specifies the resource: an App Store entry's ui, manifest, and mock-data fixtures. The 'Internal' prefix and 'Not useful to call directly' clearly distinguish it from sibling tools like install_from_app_store or get_app. It's specific about the purpose: rendering a sandboxed preview card.

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 marked 'Internal' and 'Not useful to call directly,' which tells agents not to invoke it directly. However, it does not name an alternative tool to use instead, so it earns a 4 rather than 5.

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

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

Annotations already establish idempotency and non-read-only behavior. The description adds valuable details beyond that: argument validation against declared params, failure responses including the declared schema, and success replies containing the return value plus a per-write receipt. These behaviors are not present in annotations, enriching the agent's expectations without contradiction.

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

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

The description is two sentences, front-loaded with the core purpose, then adding behavioral details. Every clause adds information: purpose, no-UI nature, validation, error handling, and return content. There is no redundancy or 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 tool with 5 parameters, nested args, and an output schema, the description covers the essential operational aspects: what it does, how args are validated, how failures are reported, and what the success reply contains. It omits nuances like the actor enum's effect, but the output schema and overall clarity keep it reasonably complete.

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

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

With only 20% schema description coverage, the description carries a heavier burden. It does clarify that 'args' are checked against the app's declared parameters, giving meaning to that field. However, it does not explain 'actor' or add any semantics beyond what the names imply for 'app' and 'function'. This is adequate but not fully compensating for the low 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?

The description starts with a specific verb-resource pairing: 'Run a function an app declares (manifest.functions)'. The added phrase 'data in, data out, no UI needed' immediately distinguishes this from UI-oriented siblings like open_app and app_html, making the tool's scope unmistakable.

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

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

The description provides clear context that this is for headless function execution ('no UI needed') and even gives retry guidance after failures ('failures return the declared schema so the retry needs no extra read'). However, it does not explicitly name alternative tools or state when not to use it, stopping short of full exclusion 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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds context on 'group' and 'fields' but does not disclose additional behavioral traits such as side effects, ordering, or what happens if the collection doesn't exist. No contradiction with annotations is present.

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

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

The description is two sentences long, front-loaded with the core action, and uses no redundant words. It efficiently explains the tool's purpose and two key parameters without superfluous detail.

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

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

Despite having an output schema and annotations, the description leaves 'position' and 'actor' undefined, which are important for correct invocation. The core action is clear, but the tool has 6 parameters and nested objects, so a fully complete description should cover more parameter semantics. It meets the minimum viable threshold but has gaps.

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

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

Schema description coverage is low (17%), so the description's clarification of 'group' as a lane/section and 'fields' as a JSON object with an example is valuable. However, 'position' and 'actor' remain unexplained, and 'collection' is only implied, not explicitly defined. The description partially compensates for the schema gaps but does not fully cover all parameters.

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

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

The description clearly states the action ('Add an item to a collection') with a specific verb and resource, distinguishing it from sibling tools like data_update_item, data_move_item, and data_delete_item. It also elaborates on the 'group' and 'fields' parameters, making the purpose unmistakable.

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

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

The description implies usage for adding new items but does not explicitly state when to use this tool versus alternatives like data_update_item or data_move_item. There is no mention of exclusions or alternative scenarios, leaving the guidance implicit 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?

Discloses critical behavioral traits: all-or-nothing transaction with first-failure rollback and error naming, reply format ({id, seq}), and that rows are not returned. This goes well beyond the annotations, which only hint at idempotency and non-destructiveness, adding real operational context for the agent.

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, each earning its place: purpose, command format, transaction semantics, and response format. No filler or redundancy; the description is front-loaded with the most important constraint (ONE transaction, up to 200 writes).

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 complex batch tool, the description covers the essential operational aspects: usage examples, command schema (via reference to sibling tools), transaction behavior, failure reporting, and response format. The presence of an output schema reduces the need to detail return values, and annotations handle safety hints.

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% (actor lacks description), but the description compensates by fully explaining the 'commands' array structure, linking each command to the corresponding single-write tool and enumerating the 'type' values. It also clarifies command_id as an idempotency key. The actor parameter remains undocumented in text but is self-evident via its enum.

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

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

Specific verb+resource+scope: 'Apply up to 200 writes in ONE transaction' clearly states the batch-write purpose. The description explicitly differentiates from single-write tools with 'instead of one call per row' and lists the four supported write types, making the tool's role unmistakable.

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

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

Provides explicit use cases ('seeding an app' or 'filling a board in one go') and contrasts with alternatives ('instead of one call per row'). It also identifies the 200-write limit and implies when the tool is appropriate by mapping commands to the single-write tools.

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

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

Even with readOnlyHint=true, the description adds valuable behavioral context: it reveals that user widget edits are included in the change stream, events are returned oldest-first with full details (actor, item id, fields), and omitting 'since' only returns the current position. This goes well beyond the structured 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 dense sentences carry the entire behavioral contract without repetition. The most important concept ('what changed since you last looked') is front-loaded, and every clause adds necessary detail about marks, return ordering, and event contents.

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

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

The description fully covers the tool's semantics: what events are returned, the meaning of 'since', how to continue paging via next_since, and the surprising inclusion of user widget edits. With an output schema present, there is no need to enumerate return fields, making this complete for the tool's complexity.

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%, so the description's burden is moderate. It enriches the 'since' parameter by explaining acceptable mark types (write ack seq, data_list version, next_since) and the consequence of omitting it. It does not elaborate on 'collection', but the overall context is sufficient; the extra mark semantics push this above 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 uses a specific verb ('returns') and clearly identifies the resource: a collection's event stream since a held ledger position. It distinguishes this from sibling tools by emphasizing that it includes edits made in the widget that never pass through the agent, which data_list and data_version do not cover.

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

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

The description provides clear when-to-use guidance by explaining how any existing mark (write ack seq, data_list version, or next_since) serves as the 'since' parameter. It does not explicitly state when NOT to use this tool or name an alternative for full collection snapshots, though it references data_list's version as a source, which implies its role.

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, covering the safety profile. The description adds useful behavioral context: it guarantees a full enumeration of all collections and explicitly states 'Renders no UI.' No contradiction with 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 concise sentences, each delivering distinct value: what is listed, when to use the tool, and the rendering behavior. The core action is front-loaded with no filler.

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

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

For a parameterless listing tool with an output schema and read-only annotation, this description covers scope, use cases, and behavioral nuance. Nothing essential for calling it correctly is missing.

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

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

The tool has zero parameters, so the schema conveys all there is to know. There is no parameter meaning for the description to clarify; baseline 4 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 ('List'), a clear resource ('every data collection that exists'), and the returned fields (name, item count, last activity). The phrase 'every data collection' distinguishes it from content-level tools like data_list, which operate on items within a collection.

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

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

Provides explicit when-to-use guidance: 'Use when unsure where data lives, what boards the user has, or which collection to bind an app to.' It does not explicitly list exclusions or name alternative tools, but the contexts are concrete enough to guide selection.

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

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

The annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond that: it discloses the confirmation_required behavior and guides the agent on how to handle it, including referencing the 'note' field. This is useful, even though 'note' is not defined in the schema.

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

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

The description is brief, two sentences, and front-loaded with the primary purpose. The second sentence is somewhat dense but still focused. No excessive words, though the wording could be clearer about the 'note' reference.

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

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

Given the tool has 6 parameters and an output schema, the description is moderately complete. It explains the confirmation flow, which is important for a destructive operation, but it omits details about other parameters and edge cases. The output schema exists, so return values are not required, but the description could be more thorough about the delete process.

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%, so the description must compensate for the underdocumented parameters. It adds some meaning to request_state (required for confirmation flow) but does not explain actor, expected_version, require_confirmation, or the idempotency key usage beyond what the schema already says. The reference to 'note' is confusing because it is not a parameter.

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

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

The description clearly states the action and resource: "Delete an item permanently." It distinguishes from sibling tools like data_add_item, data_update_item, and data_move_item by specifying the permanent deletion operation.

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

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

The description provides clear usage context when it explains the confirmation_required flow: show the note and resend with request_state. However, it does not explicitly discuss when to use it versus alternatives or exclusions, though that is somewhat implicit given the tool's name.

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

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

Beyond the readOnlyHint annotation, the description discloses key behavioral details: paging follows a 'live keyset walk,' items can be skipped or repeated, pages contain limit/total/next_cursor, and match has operator semantics. This adds substantial operational context that annotations alone do not provide.

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

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

The description is dense but every sentence contributes: purpose, UI exclusion, page shape, filter semantics, and paging caveat. It front-loads the core behavior and groups related concepts cleanly without redundant restatement of schema fields.

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

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

For a 5-parameter tool with an output schema, the description covers selection scope, filtering operators, paging behavior, and edge cases. The output schema handles return-value structure, so nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is already high at 80%, but the description adds crucial meaning: it explains the match parameter's bare-value-equals behavior, lists available operators, and specifies numeric versus lexicographic comparison. It also clarifies paging semantics tied to limit and cursor beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Read items in full,' and explicitly states the output includes 'every field, plus the item id you need to update or delete it.' It also distinguishes itself from a UI tool ('No UI (use open_app for that)'), making its scope clear relative to siblings.

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

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

It gives explicit routing guidance by stating 'No UI (use open_app for that)' and frames the tool as the way to obtain item IDs needed for update or delete operations. This tells an agent when to use data_list versus relevant alternatives like open_app or mutation tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the operation semantics but does not disclose additional behaviors such as optimistic concurrency via expected_version or the role of the idempotency key.

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, well-structured sentence that is front-loaded and concise. Every word adds value, with an example to clarify the use case.

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

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

The description is minimally viable given the annotations and output schema, but it lacks guidance on when to use this versus data_update_item and does not address the expected_version or actor parameters. It is adequate but not comprehensive for a mutation 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?

The description clarifies the purpose of 'group' and 'position' by tying them to the move operation, but schema description coverage is only 17%. It does not explain parameters like expected_version or actor, leaving a gap for a 6-parameter tool.

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

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

The description clearly states the action ('Move an item') and the target scope ('to another group and/or position'), with a concrete example ('e.g. kanban column'). This distinguishes it from sibling tools like data_update_item or data_delete_item.

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

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

The description implies when to use it (when you need to change an item's group or position) but does not explicitly mention alternatives or exclusions. It falls short of naming other data_* tools or stating when not to use it.

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

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

Beyond the annotations (non-read-only, non-destructive, idempotent), the description discloses shallow-merge semantics, null-based field removal, and optimistic concurrency. It does not cover conflict error handling or permission requirements, but the optimistic concurrency mention is a valuable behavioral hint.

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

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

The description is two short sentences with no filler. It front-loads the verb and object, uses a parenthetical for the key removal detail, and ends with a concise concurrency note.

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 an output schema and annotations, the description covers the core behavioral contract well. The only minor gap is the lack of explicit conflict-handling guidance, but the optimistic concurrency mention plus the schema's expected_version description suffice.

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 40%, and the description compensates for the 'fields' parameter by explaining shallow merge and null removal. It also hints at expected_version via optimistic concurrency, but leaves 'actor', 'id', and 'command_id' semantics to the schema or inference.

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 action ('Shallow-merge fields into an item') with a clear resource (an item) and defines the semantics of key removal via null. This clearly distinguishes it from sibling tools like data_add_item, data_delete_item, and data_move_item.

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 clearly implies the tool is for updating existing items via shallow merge, and the null-removal note adds important usage detail. It doesn't explicitly state exclusions or alternatives, but the operation is distinct enough within the data_* sibling group.

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 safety profile is covered. The description adds valuable behavioral context: the meaning of seq as a global change indicator, the existence of sub-counters, and the cost-effectiveness ('cheapest possible'). This goes beyond the structured annotations, though it doesn't discuss edge cases or rate limits.

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

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

The description is three sentences, each earning its place: first states what it returns, second explains the decision rule, third provides context. No fluff or repetition.

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

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

For a simple no-parameter tool with an output schema, the description fully covers purpose, usage, and behavioral implications. It explains when to use (before re-listing) and what the return value indicates, making it complete for an agent to decide and invoke.

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

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

The tool has zero parameters, so the baseline is 4. The schema coverage is trivially 100%, and the description doesn't need to explain parameters. It adds no additional parameter semantics but none are needed.

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

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

The description clearly states the tool returns the global change counter (seq) plus sub-counters, with a specific verb ('returns') and resource ('change counter'). It also distinguishes itself from siblings like data_changes by positioning as 'the cheapest possible change check' and explaining its use for skip re-reading.

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

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

Provides explicit when-to-use guidance: 'If seq hasn't moved since you last looked, NOTHING changed anywhere — skip re-reading' and 'Widgets use this for adaptive polling; you can too before re-listing a collection.' This tells the agent exactly the context for using this tool over 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?

The description adds substantial behavioral context beyond the annotations: tombstone semantics (data/files/history kept), cascade's two-step confirmation with disposition plan, and the permanent, non-undoable nature of cascade. It also clarifies that shared or unprovable collections are always kept, which is critical for understanding the tool's impact. No contradiction with annotations; destructiveHint and idempotentHint are consistent.

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

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

The description is dense but efficient; every sentence adds critical information about behavior or usage. It is front-loaded with the primary action and then elaborates on modes and confirmation. Slightly lengthy due to the complexity of the cascade flow, but still concise given the tool's nuance.

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 tool with no output schema, the description is remarkably complete. It covers the two deletion modes, the irreversible-cascade chain, the disposition plan requirement, and the preservation rules for shared/unprovable collections. This provides enough context for an agent to execute correctly and explain the outcome to a user.

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 description significantly enhances understanding of the 'data' parameter by explaining tombstone vs cascade and the request_state flow. However, it does not cover the semantics of 'name', 'actor', or 'command_id' beyond the schema (which itself omits descriptions for name and actor). With schema coverage at 60%, the description partially compensates but leaves some param meanings implicit.

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

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

The description clearly states 'Delete an app from the registry' — a specific verb and resource. It further distinguishes two deletion modes ('keep' tombstone vs 'cascade' permanent) and explicitly references restore_app as the undo path, setting it apart from sibling tools like restore_app 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?

Provides explicit guidance on when to use each mode: use 'keep' for a reversible tombstone and 'cascade' for permanent deletion. It instructs the agent to read the disposition plan to the user and re-send with request_state, effectively outlining the confirmation workflow. Also warns that cascade is not undoable and that shared/unprovable collections are always kept, helping the agent decide appropriately.

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

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

Beyond annotations, the description reveals important behaviors: edits apply atomically, range offsets address the expected_version document, string edits apply after ranges, and the #oma-manifest block is re-read on save. This adds meaningful context not visible in 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?

The description is dense but every sentence earns its place: purpose, form definitions, ordering, overlap constraint, atomicity, and manifest behavior. It is front-loaded with the core distinction and uses compact, meaningful phrasing.

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

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

Given the tool's complexity and the rich schema/output schema, the description covers the essential operational details: edit forms, constraints, ordering, atomicity, and expected_version source. Nothing critical for an agent 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?

The schema already covers most parameters (80%), so the baseline is 3, but the description adds value by explaining the RANGE and STRING forms, the exact-once matching rule for old_string, replace_all, and the relationship between offset/length/expect_hash and get_app output.

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: 'surgical edits to an app' without round-tripping the whole source. It clearly distinguishes itself from full-source alternatives like save_app and names the two edit forms, RANGE and STRING, with concrete semantics.

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

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

It explicitly says when to use this tool (surgical edits, not full round-trip), how to choose between RANGE and STRING forms, and gives ordering constraints (string edits apply after ranges). It also references get_app for the expected_version and range hashes, providing clear operational 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 and readOnlyHint=false. Description adds 'permanently' which indicates irreversibility, and specifies scope to files an app has stored. However, no details on error behavior or version considerations.

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, no waste. Directly communicates action and scope.

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?

Tool has 6 parameters and output schema, but description is extremely minimal. It doesn't address idempotency implications or concurrency controls (expected_version). However, given annotations and output schema, it's moderately complete for a simple delete.

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% (command_id), and description provides no parameter explanations. Parameter names are self-evident, but description does not clarify semantics for expected_version, actor, or request_state.

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?

Description uses specific verb 'Permanently delete' and resource 'one file an app has stored,' clearly distinguishing from delete_app and file_write tools. Scope is precise.

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

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

No explicit guidance on when to use vs alternatives like file_write or delete_app. Context implies deletion of app-stored files, but no direct exclusions.

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

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

The description goes beyond readOnlyHint=true by disclosing pagination mechanics ('limit/cursor page through'), prefix narrowing, and that it returns a page plus usage totals rather than a flat list. 'Renders no UI' is a genuinely useful behavioral exclusion. Annotations already cover the read-only safety profile, so the description adds meaningful behavior context without contradicting them.

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

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

Three terse, information-dense sentences with the core purpose and return shape front-loaded, followed by only the details that disambiguate it from siblings. No filler; 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?

For a read-only list tool with a 100%-documented schema, a true output schema, and safety annotations, the description is nearly complete: it covers return fields, paging, filtering, and file-type semantics. Minor gaps remain — behavior for a nonexistent app, permission requirements, and explicit differentiation from file_read — so it falls just short of a 5.

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 all four parameters are already documented individually. The description adds only the relational framing that limit/cursor form a paging mechanism and prefix narrows, which is mildly useful but largely redundant with the schema's own notes (e.g., 'opaque cursor from the previous page's next_cursor'). Baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource (the files an app has stored), and names the return shape ({path, size, mime, version} plus usage totals), distinguishing it at a glance from data_list. It also clarifies what the files are (opaque user files like attachments/exports) and what the tool is not ('Renders no UI').

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

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

Provides clear context: 'These are opaque user files... separate from its structured data collection' implicitly routes structured-data queries to the data_* siblings. It stops short of explicitly naming alternatives or stating when not to use it, so it is contextual rather than fully prescriptive.

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

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

Beyond the readOnlyHint annotation, the description discloses the full windowing contract: offset/length select the window, data_base64 carries exactly that window, next_offset continues, and sha256 hashes the whole file so reassembly is verifiable. This is substantial operational context that annotations and schema alone do not provide.

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

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

The description is compact and front-loaded with the core action. Every sentence contributes useful information: window selection, continuation semantics, and reassembly/integrity checking, with no filler or repetition of schema details.

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

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

For a windowed file reader, the description covers selection, continuation, reassembly, and integrity checking. With an output schema present, this is sufficient for an agent to call the tool correctly and handle multi-window reads without additional inference.

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

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

The schema already documents path, length, and offset, and the description reinforces their interaction: offset and length select the byte window, and next_offset continues reading. It adds useful meaning about reassembly and whole-file sha256 verification, though the app parameter remains undocumented.

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

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

The description opens with a clear, specific action: 'Read one file an app has stored' and identifies the resource as an app-stored file with windowed byte access. It is unambiguous about what the tool does, though it does not explicitly contrast itself with sibling tools like get_app or file_list.

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 intended use is implied: use this when you need to read the contents of one of an app's stored files, especially when windowed reads are needed. It references the same window grammar as get_app, but it does not explicitly state when to prefer file_read over alternatives or when not to use it.

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

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

Beyond the annotations (destructive, idempotent), the description adds valuable behavioral details: overwriting bumps version, writes are limited to a few MiB, files persist, and are app-owned and reusable across chats. This enriches the agent's understanding of side effects and constraints without contradicting any annotation.

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 sentences, front-loaded with the core purpose, and every sentence contributes meaningful information (purpose, data_base64 handling, version bump, size limit, persistence). No redundant wording or filler.

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

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

Given the output schema exists, the description fully covers the essential context: file persistence, overwrite behavior, versioning, size constraints, and cross-chat reusability. It is complete enough for an agent to use the tool correctly without further clarification.

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%, but the description elevates the meaning of data_base64 with explicit guidance ('pass any file the user gave you or that you generated') and clarifies overwrite/version semantics that tie to expected_version. Other parameters are adequately self-describing in the schema.

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

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

The description clearly states the tool's function: 'Store a file for an app (create or overwrite by path).' The verb 'store' plus the resource 'app file' and the create/overwrite behavior precisely distinguish it from sibling tools like file_write_begin and file_write_chunk, which handle multi-part writes.

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

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

The description provides clear context: it accepts any file the user gave or the agent generated, and it notes that single-call writes are limited to a few MiB, implying larger files should use the chunked write tools. However, it does not explicitly name the alternative tools, so it stops short of a fully explicit when-not-to-use directive.

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, so write behavior is known. The description adds valuable beyond annotations: uploads expire after 30 idle minutes, per-file ceiling is 250 MiB, and an upload_id is returned. This contextualizes the operation's lifecycle without contradicting 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?

The description is compact yet information-dense. Each sentence serves a purpose: stating the trigger condition, outlining the workflow steps, and noting limits. No filler or redundant phrasing.

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

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

Given the tool is part of a multi-stage process, the description explains the entire flow (begin → chunk → commit) and critical constraints. It also notes an upload_id is returned, and since an output schema exists, return-value details are not required. Context is complete for an agent to select and invoke 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?

The only parameter 'app' is fully described in the schema as 'the app this file will belong to' (100% coverage). Since the schema carries the full parameter meaning, the description need not add more. It does not provide extra parameter details, matching the baseline for high 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?

The description clearly states the tool's purpose: 'Start a chunked upload for a file too big for file_write's single call.' It uses a specific verb and resource, and distinguishes from siblings by explicitly referencing the chunked upload workflow and naming file_write, file_write_chunk, and file_write_commit.

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 guidance is provided: 'for a file too big for file_write's single call.' It also maps the full sequence of operations: returns upload_id, use file_write_chunk to send bytes, then file_write_commit to name the file. Additionally, it includes expiration and size constraints that affect when to use.

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 provide safety flags (readOnlyHint false, etc.). The description adds valuable behavioral context: chunks must be strictly ordered, and resending with the same seq is a safe no-op. This goes beyond annotations without contradicting them.

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

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

Two focused sentences: the first states purpose, the second explains ordering and retry semantics. No redundancy, front-loaded, every word earns its place.

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

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

For a tool in a multi-step upload flow, the description covers essential lifecycle context (started with file_write_begin), ordering, and retry safety. Output schema exists, so return values are documented elsewhere. Missing explicit error cases but not necessary for core usage.

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 covers two of three parameters with descriptions (seq and data_base64). The description reinforces seq's purpose (0-based index for safe resend), adding meaning beyond the schema's description. upload_id lacks description, but the coverage is sufficient.

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

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

The description clearly states the tool appends the next chunk of base64 bytes to an upload started with file_write_begin. It names a specific verb and resource, and the mention of file_write_begin distinguishes it from sibling tools like file_write_commit and file_write.

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

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

It implicitly defines when to use: after file_write_begin, before commit, and explicitly requires sending chunks in order, one at a time. It also explains safe resend behavior with seq, giving clear usage context. However, it does not explicitly name alternatives or exclusion 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?

Annotations already indicate destructive and idempotent behavior, but the description adds valuable context: the upload is consumed regardless of success or failure, and retries from file_write_begin are the recovery path. This goes beyond the annotation flags and helps the agent understand the consequences.

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

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

The description is two sentences with no redundancy. It front-loads the purpose and includes a critical behavioral note about upload consumption and restart, making every word count.

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

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

The tool is moderately complex due to the chunked upload workflow, but the description covers the finalization action, the equivalence to file_write, and failure recovery. Output schema exists, so return details are not needed. The main gap is parameter documentation, but overall the picture is reasonably complete.

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

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

Schema description coverage is only 40%, and the description does not compensate by explaining parameters like mime or expected_version. It implicitly clarifies the role of path (target file name) and upload_id (the upload), but does not add enough detail to fully overcome the schema gaps.

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

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

The description clearly states the tool finalizes a chunked upload into an app file, using specific verbs like 'finalize' and 'create or overwrite'. It distinguishes itself from file_write by calling itself the chunked equivalent, which precisely identifies its role among sibling tools.

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

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

The description explains this is the chunked counterpart to file_write, implying it is used after chunked upload steps. It also provides a clear 'on failure, restart from file_write_begin' guideline, giving a recovery path. While it does not explicitly list when-not-to-use or alternative tools, the context is strongly 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?

Beyond the readOnlyHint annotation, the description discloses mutilation risk, the destructive consequence of editing from a mutilated read, next_offset/total continuation semantics, node-based jumps, and version/hash expectations. This is rich, non-obvious behavior that annotations alone would not 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?

The description is dense but each sentence earns its place: window mechanics, safety rationale, version/hash, node behavior, and manifest behavior. There is no redundancy or 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 complex windowed-read protocol, the description covers the window mechanism, continuation, safety rationale, edit-handshake values, node targeting, and the manifest alternative. Nothing essential for correct invocation appears to be 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 high, but the description adds real meaning beyond the schema: offset/length define a selectable window, next_offset continues it, total is full length, node targets an element, slot:manifest bypasses window mechanics, and version/hash feed later edit operations. This goes far beyond the parameter descriptions.

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 ('Read an app's ui source') and adds clear windowing mechanics plus a manifest slot alternative. It is much more specific than the title, but it does not explicitly name or contrast sibling tools, so it stops just short of full differentiation.

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

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

It gives strong contextual guidance: windowed reads exist because oversized results may be silently mutilated, and the returned version/hash are meant for edit_app/save_app. It does not explicitly list when to use an alternative tool, but it conveys the right decision 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 readOnlyHint=true, so the safe read nature is known. The description adds behavioral context by enumerating what the guide contains (contract, tokens, data model, template), making the tool's output predictable. It does not introduce contradictions and offers meaningful detail beyond the structured 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?

The description is two punchy sentences: the first delivers an imperative usage directive, the second lists the concrete contents. No filler or redundancy; every word earns its place and the most important instruction is front-loaded.

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

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

For a simple guide tool with one optional enum parameter and no output schema, the description covers the core return value well (contract, tokens, model, template). It does not list the individual chapters (functions, embed, style), but those are enumerated in the schema, so completeness is adequate. Slightly more detail about how the topic parameter alters the output would push it to 5.

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%: the 'topic' parameter is fully documented with an enum and a clear description ('which chapter... Each chapter stands alone'). The tool description does not need to repeat this. It neither adds nor detracts, 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 uses a specific verb ('Returns') and names the exact resources delivered: the window.oma API contract, CSS design tokens, data model, and a minimal working app template. It also includes an explicit 'READ THIS FIRST' instruction, clearly distinguishing it as an orientation/guide tool from siblings like get_app or edit_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 opening 'READ THIS FIRST before creating or editing an app' is an explicit when-to-use directive. It signals the tool is a prerequisite step before mutation tools like save_app or edit_app. The description does not list alternatives, but the strong directive makes usage context unambiguous.

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

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

Beyond the annotations (idempotent, non-destructive), the description reveals that installed apps rely on the store for UI updates and that seeding data via data_batch is critical to avoid a half-delivered app. This is important behavioral context not present in 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?

The description is concise and front-loaded with the core purpose, followed by usage and a high-value workflow warning. Every sentence earns its place with no fluff.

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

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

Given the tool's simplicity (2 parameters, output schema present) and good annotations, the description covers purpose, usage, and behavioral expectations comprehensively. No significant gaps remain.

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

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

The input schema already fully documents both parameters (name and command_id), so the description adds no new parameter-level meaning. The mention of app_store_list for the name parameter is already captured in the schema's description.

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

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

The description clearly states the tool installs or updates a ready-made app from the built-in App Store into the user's registry. It uses specific verbs and resources, and distinguishes from siblings by mentioning app_store_list and contrasting with edits.

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 instructs to use app_store_list to see what is available, and notes that UI updates come from the App Store rather than edits, implying this tool is for installing/updating store apps instead of editing them. This provides clear when-to-use and when-not-to-use 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=true, so the read-only nature is known. The description adds behavioral context by noting the registry is reusable across chats, lists the user's openable apps by default, and allows widening via kind/visibility.

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

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

Three sentences, front-loaded with the core purpose, each adding meaningful information: registry scope, the reuse-over-create guideline, and parameter usage. No wasted words or redundancy.

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

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

For a read-only list tool with three optional params and no output schema, the description covers the essential context: what is listed, default filtering, lookup behavior, and how to broaden the search. It is self-sufficient and well-rounded.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds value by mapping parameters to use cases: 'pass name to look one up' and 'widen with kind/visibility', which clarifies intent beyond enum definitions.

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

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

The description clearly states the tool lists UI apps in the registry, with a specific resource ('UI apps') and scope ('reusable across all chats'). It distinguishes itself from creating or opening apps by framing the registry as a lookup surface.

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

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

Provides explicit guidance: 'prefer opening it over creating a new one' and explains how to narrow results with name or widen with kind/visibility. It does not name sibling tools explicitly but gives enough context for choosing this over a create/open action.

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. The description adds useful behavioral context by framing the result as an 'interactive widget,' noting immediate availability for recently saved apps, and comparing against dedicated open_<name> tools. It does not contradict the annotations, though it could elaborate on what an interactive widget entails.

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

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

The description is compact—three sentences, each earning its place: purpose, usage/alternative, and preference. It front-loads the core action and keeps supporting information tightly relevant.

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

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

Given the tool's simplicity (2 params, output schema available, read-only annotations), the description covers the essential context: purpose, usage scenario, timing, and a best practice for reuse. The output schema handles return-value details, so no further description is needed.

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

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

Schema description coverage is 100% for both parameters, so the schema carries the parameter details. The description reinforces that the app parameter names a registry app and hints at collection binding via the reuse guidance, but does not add substantial new meaning beyond the structured schema.

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

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

The description opens with a specific verb-resource pairing: 'Open ANY app from the registry by name as an interactive widget.' It immediately distinguishes from data_list ('no UI') and dedicated open_<name> tools, making the tool's role unambiguous.

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

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

Explicitly states when to use the tool ('when the user wants to SEE or OPERATE the data') and identifies the alternative for reading facts (data_list). It also gives timing guidance (works immediately for recently saved apps vs dedicated tools that may take a while) and a reuse preference for collections.

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 goes well beyond annotations by detailing the atomic nature, preservation of other keys, OCC guard, new version creation with history, no-op for existing apps, and refusal to downgrade. It also clarifies idempotency via command_id, aligning with the idempotentHint annotation. No contradiction with 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?

The description is compact yet packed with essential information: action, effects, constraints, and alternatives. Each clause serves a purpose (atomicity, manifest behavior, versioning, no-op, downgrade refusal). No redundant or filler content.

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

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

Given the tool's moderate complexity, the description covers the core behavior, edge cases (no-op for already apps, downgrade refusal), and security/correctness aspects (OCC-guarded, history kept). An output schema exists, so return values are not required in the description. The description is sufficient for an agent to correctly select and invoke the tool.

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

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

Schema description coverage is 100% for both parameters (name, command_id), each with meaningful descriptions. The tool description adds no further parameter-specific semantics, but the schema already handles this, earning the baseline 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?

The description clearly states the tool's purpose: upgrading a 'visual' app to a full app by flipping the kind in the manifest. It uses specific verbs ('Upgrade', 'promote'), identifies the resource ('kind:"visual" app'), and distinguishes from sibling tools like save_app by explicitly noting demotion is handled elsewhere.

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 provides when-to-use and when-not-to-use guidance: 'Already an app is a no-op' indicates the tool is only for visual apps, and 'downgrades are refused — demoting is an author edit (save_app with the manifest)' names the alternative tool for demotion. This clears up potential confusion with save_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 provide idempotentHint=true and destructiveHint=false; the description adds valuable context that the restore is non-destructive ('nothing is lost — history is preserved and you can roll forward again') and that it creates a NEW current version. This goes beyond structured metadata.

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

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

The description is concise, front-loading the core purpose, then adding workflow. The parenthetical about non-destructive behavior is useful but makes the sentence dense. Overall, every sentence earns its place.

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

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

For a 3-parameter tool with no output schema, the description covers the action, non-destructive nature, usage trigger, prerequisite, and post-restore step. It is complete enough for an agent to select and invoke the tool correctly, especially with sibling context.

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

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

The schema covers 'checkpoint' (with description) and 'command_id', but 'name' remains undocumented. The description adds context for 'checkpoint' via app_history but does little to explain 'name' or further clarify command_id. Schema coverage is 67%, so the description only partially compensates.

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

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

The description clearly states the tool's function: rolling an app back to an earlier checkpoint by re-saving its HTML as a new current version. It distinguishes from siblings like app_history (which lists checkpoints) and open_app (which views), and clarifies it's non-destructive.

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

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

Provides explicit when to use ('when a newer edit broke the UI'), prerequisite ('Get the checkpoint number from app_history'), and follow-up action ('after restoring, open_app to view it'). Does not mention when-not or alternatives, but gives 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?

This goes far beyond the annotations. It discloses slot-merge semantics, manifest null clearing, snapshot creation for every save, history retention, and the required immediate open_app call. An agent understands the tool's side effects without experimentation.

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

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

Dense and front-loaded with the core purpose, then systematically covers slots, versioning, and next action. Every sentence earns its place and there is no filler or repetition of schema text.

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

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

For a 6-parameter upsert with a rich schema and output schema, the description is complete: it covers create/update behavior, slot semantics, clearing, versioning, and the immediate next step. It also points to get_app_guide for contract details, leaving no material gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the two-slot update model, the ui contract, manifest null behavior, and the 'creating needs ui' constraint. It does not expand on command_id or expected_version, but the schema already covers those clearly.

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

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

The description opens with a specific verb and resource: 'Create or update a UI app in the persistent registry.' It clearly distinguishes save_app from siblings like open_app and get_app by emphasizing slot-based updates, version snapshotting, and the required follow-up with open_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 description gives clear operational context: omitted slots keep current values, creating requires ui, manifest null clears the declaration, and 'after saving, open it IMMEDIATELY with open_app.' It does not explicitly name exclusions or alternative tools such as edit_app or restore_app, so it stops short of a 5.

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

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

Annotations already cover idempotency and non-destructiveness; the description adds the privileged-auth requirement, the reserved-key restriction, and the upsert semantics in the settings collection. This goes beyond the structured annotations without contradicting them.

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

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

Two dense sentences carry the core purpose, exclusivity, and write behavior. The most important differentiator ('the ONLY tool that can write them') is front-loaded, with no filler.

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

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

Given the rich schema, an output schema, and annotations, the description provides the essential contextual framing: target keys, elevated privileges, exclusivity, and upsert behavior. Nothing needed for correct selection or 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?

Schema description coverage is 100%, and the schema itself provides detailed parameter semantics for key, value, and command_id. The tool description does not add parameter-level meaning, but with full schema coverage it does not need to.

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 ('Privileged writer') and precise resource scope ('reserved settings keys (security:* / policy:*)'), and explicitly differentiates from the generic data_* tools. An agent can immediately understand both what it does and how it is distinct.

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

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

Explicitly names the alternative family (data_* tools) and explains the exclusion: data_* tools refuse reserved keys, so security_set is the ONLY writer for these keys. This gives the agent a clear routing rule.

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 the description reinforces this with 'Read-only' while adding context about engine ownership, the settings app rendering, and the boundary with oma.pref(). This adds useful 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?

The description is compact and front-loaded, but the phrase 'Read-only.' is redundant given readOnlyHint=true. Still, both sentences earn their place by explaining ownership, rendering, and the oma.pref() distinction.

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

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

For a zero-parameter read-only catalog tool with an output schema, the description is complete: it names the resource, the contents, the consumers, and the boundary against runtime value retrieval. 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter information to add. The description still clarifies what the catalog entries contain (key, type, label, default, options), which helps an agent understand the output.

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 ('describes') and resource ('engine-owned catalog of SHARED preferences'), and clearly distinguishes the tool from effective-value retrieval by noting that apps read values via oma.pref() while this tool only describes what exists.

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 the intended use: inspect the catalog of shared preference definitions rather than read effective values. It explains the relationship to oma.pref(), though it does not explicitly name alternatives or state when not to use it.

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