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

With no annotations, the description carries the full burden and does well: it discloses that this mutates the phone, that it backs up first, that it verifies afterward, and that it requires a token from the latest diff. It does not state reversibility beyond 'backs up' or note failure modes, keeping it below a 5.

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

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

Three short sentences, action first, prerequisite and safety behavior after. Zero filler.

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

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

An output schema exists, so return values need not be described; what remains — the mutation's effect, its prerequisite, and its backup/verify safety net — is all present for a single-parameter commit tool.

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

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

Schema coverage is 0%, so the description must supply meaning for apply_token — it does, stating the token must come from the latest diff, which is a real precondition the schema does not express. No format or expiry details are given.

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

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

States a specific verb and resource ('Write the draft to the iPhone'), which unambiguously separates it from siblings like diff, render_preview, and reset_draft — those inspect or discard, this one commits.

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

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

Gives a hard gating condition ('Only call when the user explicitly asked to apply this draft'), which is a clear when/when-not rule. It stops short of naming alternate tools, but the exclusion is strong enough that misuse is unlikely.

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

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

With no annotations, the description carries the whole burden and does meaningful work: it discloses external network egress to Apple's public lookup API, a privacy-relevant side effect, and that results are cached locally. It omits failure behavior for unknown/invalid bundle ids and any rate-limit or latency characteristics of the upstream call.

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

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

Three short sentences, no filler, and the most decision-relevant fact (what it returns) leads. The privacy caveat follows logically from the network call mention.

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 output schema handles return shape, and the description adds the caching and egress context. But for a tool whose only parameter is optional with a null default, not explaining the no-ids behavior leaves a real gap in when/how to invoke it correctly.

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

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

Schema coverage is 0%, and the description only implicitly identifies the parameter by calling it 'bundle ids' (e.g. 'com.apple.Pages'). It says nothing about the null default, so an agent cannot tell whether omitting `ids` fetches genres for every app — a consequential ambiguity given the network caveat.

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 the returned resource precisely — 'App Store genre per app' — and even resolves the edge case that Apple's own apps report as 'Apple'. No sibling covers this same data (icon_colors, find_apps, get_icons are adjacent but distinct), so no differentiation is needed, though the description never names the action verb ('fetch/return').

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

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

Gives an explicit precondition for calling: 'only call it when the user is fine with that', tied to the concrete reason that bundle ids leave the machine. It does not name alternatives (e.g., caching, or local data sources), so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the key constraint that every top-level item and library app must appear exactly once, and that omitted dock/library fields remain unchanged, but it does not state atomicity, reversibility, permission needs, or whether changes go to a draft.

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, followed by parameter semantics and the critical uniqueness constraint. Every sentence carries useful information without padding.

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

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

The output schema covers return values, and the description covers the main inputs and validation constraint. However, for a whole-layout mutation tool with no annotations and no schema descriptions, it should clarify whether changes apply immediately or to a draft and how conflicts or duplicates are reported.

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

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

Schema description coverage is 0%, so the description must add meaning, and it does: pages is explained as row-by-row lists of ids, library as App Library apps, and dock/library omission semantics are defined. The dock parameter's format is only implied by parallelism, keeping it from a 5.

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

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

The description gives a specific verb and resource: 'Set the whole top-level layout at once.' The phrase 'whole top-level layout' clearly distinguishes this from granular sibling operations such as move, place_at, and page_op.

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 implies the right context: use this when replacing the entire top-level arrangement at once. The omission behavior for dock/library further clarifies scope, though it does not explicitly name when to use granular siblings instead.

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

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

No annotations are provided, so the description carries the full burden. It implies a mutation of layout state but doesn't say whether the change is reversible (an undo sibling exists), whether items are repositioned, or whether unplaced items are affected. With zero annotation coverage for a write operation, this is a substantial gap.

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

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

One short sentence with the effect front-loaded and the parenthetical clarification immediately after; there is no filler. The brevity is appropriate, though it edges toward under-specification rather than tightness.

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?

A mutation tool with no annotations, an undocumented required parameter, and no output description needed (an output schema exists) still leaves the agent without the state-changing and targeting information it needs. Given the crowded sibling set of layout operations, the description is too thin to call this correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the single item_ids parameter, and it does not — it never mentions that the operation targets a specific list of items or what those IDs refer to. An agent cannot tell from the description whether it passes all placed items, only the gapped ones, or something else.

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 an effect ('let placed items flow ... removes their gaps'), which is a recognizable verb+resource combination, but 'gaps' is domain jargon that isn't defined and the phrasing is metaphorical rather than operational. It also does nothing to distinguish this from siblings like remove_empty or arrange, which an agent could easily confuse with it.

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

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

There is no indication of when to call this versus remove_empty, arrange, sort_alphabetically, or place_at, all of which plausibly touch layout spacing. No prerequisites, no state requirements, and no mention of whether it should follow a place_at or precede an apply.

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

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

With no annotations, the description carries the full burden, yet it only implies mutation via 'Make'. It says nothing about whether an existing folder name causes an error or overwrite, what permissions or target scope are required, or whether the operation is reversible (undo/redo siblings exist but are not referenced). The output schema covers return values, but the write-side behavior is undisclosed.

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

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

A single dense sentence with zero filler, and the resource and placement are front-loaded. It is efficient, though its terseness is achieved partly by eliding the required 'name' parameter rather than by disciplined word choice.

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?

Four parameters at 0% schema coverage, no annotations, and 30 sibling tools demand far more than one sentence. The description never addresses the required name argument, duplicate-folder behavior, or how this differs from file_into_folders; only the output schema relieves it of documenting returns.

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

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

Schema description coverage is 0%, so the description must compensate, and it partly does: 'in order' adds meaningful ordering semantics for item_ids and 'target/index' explains the placement pair. Critically, the required parameter 'name' is never mentioned anywhere in the description, and 'index' is only implied by the slash notation rather than explained as the insertion position.

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

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

The description gives a specific verb and resource ('Make a folder') plus the placement convention ('at target/index') and contents ('holding item_ids'), which distinguishes it from rename_folder/dissolve_folder without naming them. It falls short of 5 only because it never explicitly frames itself against the crowded set of sibling placement tools (place_at, file_into_folders, arrange).

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent must infer from 'holding item_ids (in order)' that this is the creation path rather than file_into_folders or place_at, which is left entirely implicit.

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

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

No annotations are provided, so the description must carry the behavioral load. It discloses that the tool returns change details, problems, and an apply_token, which is useful, but it never explicitly states that it is non-mutating or what permissions/draft state are required.

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

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

A single compact sentence listing the three outputs, front-loaded and with no filler. It is terse but every clause contributes.

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 tool with an output schema, the description covers purpose and return content sufficiently. It could say more about the required draft state and its relationship to the apply sibling, but the structured fields cover much of the rest.

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?

Zero parameters; the description mentions apply_token as an output, not an input. With no input schema properties, the baseline of 4 is appropriate.

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

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

The description names the core output—changes from applying the draft, problems, and apply_token—so the tool's function as a diff/preview is clear. It does not explicitly contrast with render_preview or apply, so it stops shy of full sibling 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?

The mention of 'what applying the draft would change' and the apply_token implies a preview-before-apply workflow, but the description never states when to call this versus render_preview or apply, nor any prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about whether the removal is reversible (an 'undo' sibling exists but is not referenced), whether it works on folders containing apps only or also empty ones, or whether it can fail. 'Where it was' is also ambiguous — parent folder, original page, or original position.

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

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

One sentence, front-loaded with the verb and resource, with zero filler. It is arguably under-specified rather than bloated, but structurally it is efficient and readable.

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?

This is a destructive mutation with no annotations and one wholly undocumented parameter; the only thing the description adds is the destination of the apps. An output schema exists so return values need not be explained, but irreversibility, idempotency, and folder_id sourcing are all missing.

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

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

Schema description coverage is 0% and the single parameter folder_id has no title or documentation beyond its name. The description does not mention folder_id at all, its expected format, or how to obtain one (e.g., by name lookup), so nothing compensates for the schema gap.

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

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

States a specific verb ('Remove') and resource ('a folder') plus the key side effect (its apps go back to where the folder was), which differentiates it from remove_empty and file_into_folders. It stops short of naming the sibling tools it must be distinguished from, so an agent still has to infer that this is the non-empty case.

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

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

The clause 'putting its apps where it was' implies the use case (unmake a folder without losing its contents), which is real but indirect guidance. It never states when to prefer this over remove_empty, file_into_folders, or plain move, and offers no preconditions or exclusions.

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

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

With no annotations, the description carries the full burden. It usefully discloses that apps join existing folders or create new folders only with 2+ apps, and that page 1 apps are left alone by default, but it omits draft/apply behavior, reversibility, and what happens to apps already in folders.

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

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

The description is front-loaded, compact, and every sentence adds relevant information. There is no repetition 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?

The description covers the core filing behavior and the nested groups parameter, and an output schema exists so return values need not be explained. However, for a mutation tool with no annotations, it leaves important operational gaps around draft/apply workflow, undoability, and edge cases.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the required groups object format as {folder name: [app ids]} and clarifies the default first-page behavior, though it does not explicitly state what keep_first_page=false does.

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

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

The description clearly states a specific verb and resource: file loose apps into folders, with a mapping from folder names to app IDs. It implicitly distinguishes bulk filing from sibling tools like create_folder or move, but does not explicitly name alternatives.

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

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

Usage is implied by 'loose apps' and the note that page 1 apps are left alone by default, but there is no explicit when-to-use guidance versus siblings such as create_folder, move, or arrange. The agent can infer the context but is not given exclusions or 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?

With no annotations, the description carries the full burden. It discloses the substring matching approach, which is useful, but omits whether this is a read-only lookup, how matches are ranked/limited, whether matching is case-sensitive, and whether results include icons or 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?

One short sentence with no filler, and the matching fields are front-loaded. It is efficient but borders on under-specification given the absence of any other documentation.

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

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

An output schema exists, so return-value detail is not needed, and the query semantics are covered. However, with zero annotations the missing safety profile and match-behavior details keep this at minimum viable for an agent deciding whether and how to call it.

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

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

Schema coverage is 0% and the single 'query' parameter is undocumented in the schema, but the description compensates by stating it matches against name or bundle id via substring — a meaningful addition beyond the bare string type. Only the matching semantics (case, partial vs. exact) are unstated.

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

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

The description gives a specific verb ('Find') and states the matching fields (name or bundle id substring), but the resource is described as generic 'items' rather than 'apps' — the tool is named find_apps. This mismatch leaves ambiguity about whether non-app items are returned, though the bundle-id mention strongly implies app scope.

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

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

There is no guidance on when to use this vs. alternatives, no prerequisites, and no exclusions. Siblings like list_backups or app_store_categories could plausibly overlap in an agent's mind, and nothing routes 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?

With no annotations, the description carries the full behavioral burden. It does disclose the 24-app cap and ordering semantics, but omits the return format (URLs, base64, etc.), error behavior above the limit, and any permission requirements—significant gaps for a tool with no output 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?

A single front-loaded sentence that states the resource, the batch cap, and the ordering rule with zero filler.

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

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

For a simple one-parameter tool with no output schema, the description is only partially complete. It identifies the return as 'icon images' but does not say in what form they come back or how the 24-item limit is enforced.

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

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

Schema coverage is 0%, so the description must compensate. It adds that the array is capped at 24 and that order is preserved, which is meaningful beyond the bare schema, but it never clarifies what the 'ids' strings represent (app identifiers, bundle IDs, names).

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

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

The description states a specific resource (icon images) and scope (up to 24 apps, in the order given), so an agent can tell what it returns. It does not differentiate from siblings like icon_colors, which could be confused with it.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Usage is only implied by 'Icon images for up to 24 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?

No annotations are provided, so the description carries the behavioral burden. It discloses the output fields and the default all-apps behavior when ids are omitted, but it does not explicitly state that this is a read-only query, nor does it describe permissions, side effects, 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 compact and front-loaded: it states the resource and returned fields first, then immediately gives the key parameter behavior. Every clause adds useful information without waste.

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

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

An output schema exists, so the description need not explain return values in depth. For a single optional parameter, it covers the key omission behavior but omits what the ids represent and does not clarify read-only behavior, leaving minor 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 0%, and the single parameter has no schema-level explanation. The description compensates meaningfully by explaining that omitting ids returns every app, which clarifies the parameter's filtering role. It still does not specify what format the ids should be in.

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

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

The description clearly identifies the resource and returned attributes: dominant icon color per app, including family, background, hex, and hue. It lacks an explicit verb and does not directly distinguish itself from siblings like get_icons or sort_by_color, but the color-specific purpose is unambiguous.

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

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

'Omit ids for every app' provides a concrete usage rule for the only parameter. However, there is no explicit guidance on when to use this tool versus related siblings such as get_icons, sort_by_color, or find_apps, leaving usage largely implied.

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

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

With no annotations, the description carries the full burden, and it does disclose useful behavior: entries are pre-mutation snapshots and are ordered oldest first. It says nothing about whether the list is bounded, capped, or retained indefinitely, which matters for an unbounded history list.

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

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

A single front-loaded clause that defines the resource, followed by the ordering guarantee — no filler. It is arguably under-specified rather than over-long, but nothing in it is wasted.

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

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

For a no-parameter list tool with an output schema, the description covers what the items represent and their order, which is the key context. The remaining gap is retention/limit behavior, minor given the output schema documents the shape.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail and instead spends its words on semantics of the returned items.

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 the resource precisely: layouts snapshotted before each apply/restore, returned oldest first. That is more informative than the bare name and distinguishes it from show_layout or undo, but it never names a sibling or scopes what a 'backup' is relative to those alternatives.

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 explains what the entries are, not when to call the tool. An agent choosing between list_backups, undo, restore and show_layout gets no routing hint — nothing says to call this before a restore or to skip it when undo suffices.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses the 0-based index, default end placement, `before` semantics, and that 'library' means App Library only, but does not explain mutation side effects, reversibility, undo behavior, permissions, or error conditions.

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-loads the core action and target syntax. It packs useful placement details into a small space without obvious filler, though the density and unexplained fragments (`item_id`, `:N`) slightly reduce clarity.

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

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

For a mutation tool with no annotations and 0% schema description coverage, the description is incomplete. It lacks item identifier semantics, side-effect behavior, and guidance relative to siblings, even though the output schema reduces the need to explain return values.

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

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

Schema coverage is 0%, so the description must compensate for undocumented parameters. It meaningfully explains `target` formats and `index`/`before` placement, but leaves the required `item_id` and the meaning of `:N` in `folder:<id>[:N]` unexplained.

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

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

The description states a specific verb and action: move one item to a target. It enumerates target forms and clarifies the library target, so the basic purpose is clear. It does not explicitly distinguish this tool from similar siblings like `place_at`, `swap`, or `file_into_folders`.

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 target syntax and placement semantics, but gives no guidance on when to use this tool versus alternatives such as `place_at`, `swap`, or `arrange`. There are also no stated preconditions or exclusions for moving an item.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that widgets keep their pages and the dock and App Library are untouched, plus the usage-data fallback order, but it does not say whether changes are immediate or draft-only, whether they are reversible, or whether apply/commit is required.

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

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

The description is compact and front-loads the main effect, followed by the fallback usage source and untouched areas. The parenthetical fallback wording around screen_time and Screen Time is slightly ambiguous, but there is little wasted 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 layout-mutating tool with one parameter and no annotations, the description covers the high-level placement rules and exclusions, and an output schema exists so return values need not be explained. It is still incomplete because it omits the keep_first_page parameter and the draft/apply or reversibility semantics.

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

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

The single parameter keep_first_page is never mentioned in the description, and schema description coverage is 0%. The phrase 'earliest pages' does not explain whether the first page is preserved, excluded from optimization, or overwritten.

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 operation: placing the most-used apps and folders onto the earliest pages and the most-used apps onto each folder's first page. This clearly distinguishes usage-based optimization from sibling tools such as sort_alphabetically and sort_by_color, even without naming them.

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

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

The description implies when this tool is appropriate—when the user wants a usage-ranked layout rather than an alphabetical or color-based one—and it explains the fallback usage data sources. However, it does not explicitly compare against alternatives or state when not to use this tool.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that deleting a page sends its apps to the App Library, similar to iOS, which is important destructive context. It does not describe permissions, reversibility, or whether confirmation is required for insert and move.

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 compact sentence that front-loads the resource and then enumerates each operation with its relevant parameter. Every clause adds useful information with no filler.

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

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

An output schema exists, so the description need not explain return values. For a three-parameter mutation tool, it covers all operations and highlights the main delete side effect. The only notable gap is the lack of explicit routing between this page move operation and the sibling `move` tool.

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

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

Schema description coverage is 0%, so the description must explain parameters. It maps `op` to insert, move, and delete, explains that `page` identifies the page, and shows that `to` is the move destination. It does not explicitly state that `to` is conditionally required only for move.

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

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

The description clearly identifies the tool as page operations and enumerates the supported op values: insert, move, and delete. It states the resource and main behaviors, though it does not explicitly distinguish this tool from the sibling `move` tool.

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 op descriptions imply when each operation applies, such as inserting a new empty page or deleting a page. However, the description gives no explicit guidance on when to use this tool versus alternatives like `move`, nor does it state exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully states that empty spaces are left around the item and other items flow around it, but it omits important mutation details such as what happens if the target spot is occupied, whether the item is moved from elsewhere, and whether the operation is reversible.

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 action and coordinate constraints. The second sentence adds relevant behavioral context and an analogy without unnecessary repetition. Every sentence contributes to understanding the tool.

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

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

The tool has four required parameters, no annotations, and 0% schema description coverage, so the description needs to be quite complete. While it covers the row/column ranges and layout behavior, it leaves page indexing and item_id semantics unexplained, and it does not describe what happens when placing over an existing item. That is not sufficient for confident invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the row range (1-6) and column range (1-4), but it does not clarify the page parameter's indexing or range, nor does it explain item_id semantics. This leaves half or more of the parameters under-specified.

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: putting an item at an exact row/column spot on a page. It also clarifies the resulting layout behavior and grid range. It does not explicitly distinguish itself from siblings such as move, arrange, or swap, so it falls short of a 5.

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

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

Usage is implied through the phrase 'exact spot' and the row/column grid range, which suggests this tool is for coordinate-based placement. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives such as move or arrange.

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

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

With no annotations, the description carries the full burden and does disclose the key destructive trait: unapplied drafts are discarded. It does not cover failure modes (no device connected) or whether the read is live versus cached, so it stops short of full behavioral disclosure.

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

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

Two short sentences, zero waste, with the destructive warning placed immediately after the action so it is read before invocation.

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

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

An output schema exists, so return values need not be explained, and there are no parameters to document. The remaining gap is device-connection preconditions and error behavior for a tool whose name implies hardware dependency.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema is empty and unambiguous on its own.

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 and resource ('Read the Home Screen from the connected iPhone') plus the side effect of seeding a new working draft. It is distinguishable from siblings like screen_time or show_layout, but it does not explicitly differentiate itself from reset_draft, which also clears draft state.

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?

'Start a fresh draft from it' implies this is the entry point of the edit workflow, which suggests when to reach for it. However, there is no explicit guidance on when to prefer reset_draft, undo, or restore, and no stated preconditions such as requiring a connected device.

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

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

No annotations are provided, so the description carries the full burden. It does disclose meaningful scope: the effect is limited to a single draft edit and only one that was previously undone, which conveys stack-like semantics. It does not say what happens when the redo stack is empty, nor whether the operation is idempotent or itself undoable.

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

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

A single short sentence with zero waste, front-loading the verb and the exact target of the operation. Nothing could be removed without losing information.

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

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

An output schema exists and a zero-parameter signature makes this a simple tool, so the description covers what an agent needs to select and invoke it. The only meaningful gap is failure behavior when no edit is available to redo.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to clarify inputs, and nothing misleads about them.

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 (Redo) and a specific resource/scope (the last undone draft edit), which is unambiguous. The counterpart sibling 'undo' is implicitly distinguished by the standard redo/undo pairing, but the description never names it or otherwise differentiates the two.

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?

'Last undone' implies the precondition that a prior undo occurred, so usage is implied rather than stated. There is no explicit when-to-use/when-not guidance, no mention of what to do if there is nothing to redo, and no reference to the 'undo' sibling as the 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?

With no annotations, the description carries the full burden; it does disclose the key safety property that only *empty* pages and folders are removed, so populated content is untouched. It says nothing about reversibility, whether the sibling undo can recover the change, or whether this mutates the live document versus only the draft beyond the single word 'draft'.

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

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

A single front-loaded sentence with the action first and the scope qualifier last; every word earns its place and there is no filler.

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

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

The output schema covers return values and there are no parameters to document, so the remaining burden is behavioral. For a destructive cleanup operation with no annotations, the description should state whether the removal is undoable and how it relates to the draft lifecycle; that gap keeps it at minimum viable.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty properties object matches the parameterless 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?

States a specific verb ('Drop') and specific resources ('empty pages and empty folders') scoped 'from the draft', which is far more informative than the bare name remove_empty. It doesn't explicitly contrast with near-neighbours like dissolve_folder or reset_draft, so an agent must infer that only already-empty containers are targeted.

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

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

No guidance on when to reach for this versus dissolve_folder, reset_draft, or undo, and no stated preconditions (e.g. an unapplied draft must exist). The agent is left to infer usage entirely from the tool name and sibling list.

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

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

With no annotations, the description carries the full burden of disclosure, yet it provides none: no mention of permissions required, whether the rename is reversible, what happens on name collisions, or whether contents are preserved. The single sentence merely restates the mutation implied by the name.

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 single sentence is front-loaded and waste-free, but it is so terse that it under-specifies rather than being genuinely concise. Brevity here comes at the cost of essential guidance.

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?

This is a mutation tool with no annotations and 0% parameter description coverage, so the description should compensate with permission, collision, and ID-format details. It does none of that, though the existence of an output schema relieves it of return-value explanation.

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

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

Schema coverage is 0% and the description does not clarify either parameter. "folder_id" is presumably an identifier but the expected format (ID vs path vs name) is unstated, and the relationship between "name" and the rename is left 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 pairs a specific verb ("Rename") with a specific resource ("folder"), so the basic action is unambiguous. It does not, however, distinguish this from related siblings like create_folder, dissolve_folder, or move, leaving the agent to infer boundaries.

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

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

There is no statement of when to use this tool versus alternatives, nor any preconditions such as existing folder requirement or name-uniqueness rules. The agent must infer usage entirely.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the key side effect that the tool writes an HTML preview and returns a path, but it omits details such as whether an existing file is overwritten, where it is written, or any permission requirements.

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

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

The description is a single front-loaded sentence with zero waste. The parenthetical detail is compact and adds useful context without disrupting clarity.

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 tool with an output schema, the description supplies enough context to invoke it: it explains that a preview is written and a path is returned. The main missing piece is richer behavioral context around file handling, but the output schema reduces the need to describe return values.

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 there are no parameter semantics to explain beyond the baseline. The empty schema means the description does not need to compensate for undocumented 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 uses a specific verb and resource: 'Write an HTML preview' and 'return its path.' It also clarifies the comparison context ('draft vs phone, moved icons outlined'), which helps distinguish it from unrelated layout-editing siblings, though it does not explicitly name alternatives.

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 states what the tool does but offers no guidance on when to use it versus siblings such as show_layout, diff, or apply. There are no conditions, prerequisites, or exclusions provided.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that the operation is destructive to draft edits, that it resets to the phone-sourced layout as the baseline, and crucially that it is undoable. It stops short of stating permissions, whether sibling-draft state (e.g., folders) is also reverted, or any confirmations required.

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

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

A single, tightly packed sentence with the action front-loaded and the two critical qualifiers (source of truth, undoable) attached. 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 no-param, no-annotation mutation with an output schema, the essentials are covered: what is discarded, what state replaces it, and that it can be reversed. Only the comparison to undo/restore is missing, which would fully close the loop.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate or compensate for.

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

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

States a specific verb ('throw away') and resource ('draft edits'), plus the resulting state ('layout as read from the phone'). It's clear what happens, but it doesn't explicitly distinguish itself from undo, redo, or restore, which sit in the same undo-history area of the sibling 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?

Usage is only implied: the agent can infer it should call this when it wants to discard uncommitted draft edits. There's no explicit guidance on when to prefer undo, redo, or restore instead, which are close functional neighbors.

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

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

No annotations are provided, so the description carries full behavioral burden. It says 'Write a backup to the iPhone' but does not disclose whether the operation overwrites existing data, is destructive or reversible, requires permissions, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

The description is short and front-loaded, with three brief sentences that contain no filler. The terseness is efficient, though 'Same gate as apply' is vague and borders on under-specification rather than conciseness.

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?

This is a mutation tool with no annotations and one undocumented parameter. Although an output schema exists, the description does not provide enough behavioral context about restore/write semantics, data safety, or parameter usage for an agent to call it reliably.

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 'backup' has 0% schema description coverage, and the description adds no meaning beyond the parameter name. It does not clarify whether 'backup' is an identifier, file path, name, or selector, leaving the agent unable to supply the correct value confidently.

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 an action ('Write a backup to the iPhone'), but the tool is named 'restore', creating ambiguity about whether it restores from a backup or writes one. It references 'apply' but does not clearly distinguish the scope from that sibling or from 'list_backups'.

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

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

It gives a usage gate ('Only when the user explicitly asked') and points to 'Same gate as apply', which is useful context. However, it assumes the agent already knows what the 'apply' gate is and provides no explicit alternatives or when-not conditions.

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

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

With no annotations, the description carries the full burden; it discloses that device source requires no setup, that background apps are counted less and listed under 'background', and that mac source requires Share Across Devices. It does not explicitly state read-only/side-effect behavior, permissions, or failure modes.

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

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

The description is information-dense but poorly structured and contains ambiguous phrases, especially 'top apps with where they are now' and 'device vs the draft'. It is not excessively long, but wording could be clearer and better 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 two-parameter read tool with an output schema, the description covers data sources, time window, and one important counting caveat. However, it does not explain how this tool relates to the draft or when to use it alongside siblings such as optimize_by_usage, leaving context 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 0%, so the description must define parameters; it gives meaningful semantics for source values and explains days as the trailing window. It does not state the default or full valid value set, but it adds substantial meaning beyond the bare 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 identifies the resource (screen time/app usage) and lists outputs such as top apps and estimated page swipes, but it never states a clear action verb and phrases like 'where they are now' and 'device vs the draft' are ambiguous. It does not explicitly differentiate this tool from siblings such as optimize_by_usage or read_phone.

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 useful guidance for choosing source='device' versus source='mac' and notes the last `days` window, but offers no guidance on when to call screen_time instead of related sibling tools. No exclusions or alternatives are mentioned.

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

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

With no annotations, the description carries the full burden; it does clarify that the subject is the current draft (not the installed phone layout, a useful distinction from read_phone) and discloses nesting semantics for folders and widgets. However, it never explicitly states that the operation is non-mutating/read-only or what happens if no draft exists, which matters given the sibling set is dominated by mutating tools.

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

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

One dense sentence with no filler, and the core subject (the current draft) is front-loaded. The parenthetical about folders and widgets earns its space by explaining the item shape.

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

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

An output schema exists, so the description needn't explain return values, yet it spends its only sentence there. For a zero-parameter read tool that is nearly sufficient, but with no annotations the description should also have flagged read-only safety and the draft-vs-device scope explicitly.

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

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

The tool takes zero parameters, so the schema imposes nothing for the description to compensate for. Baseline applies; nothing is misdescribed.

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 concretely specifies the resource returned: the current draft with dock, all pages and App Library-only apps, including how folders and widgets are represented. The retrieval verb is only implied by the name rather than stated in the text. It also never distinguishes itself from look-alike siblings such as diff or render_preview, which also surface layout state.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no reference to any alternative. An agent must infer from the name alone that this is the read path for inspecting a layout before diff/render_preview/apply, and that it reads the draft rather than the live device (unlike read_phone).

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

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

With no annotations, the description carries the full behavioral burden. It discloses that page 1 is untouched by default and that folders and loose apps are sorted, but it does not say whether the operation is reversible, whether folder contents are affected, or what side effects occur on the home screen layout.

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

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

Two short sentences with no wasted language, and the core sorting behavior is front-loaded before the default page behavior. It is appropriately sized for the amount of information it chooses to convey.

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

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

An output schema exists, so return values need not be explained. However, with no annotations and 0% schema description coverage, the description is too thin for a layout-mutating tool: it omits side effects, reversibility, and meaningful parameter semantics.

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

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

Schema description coverage is 0%, so the description must explain both parameters. 'Page 1 is left alone by default' partially explains keep_first_page, but folders_first is not explained at all beyond its name, leaving the grouping behavior ambiguous.

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: an A-Z sort of folders and loose apps. This distinguishes it reasonably well from siblings like sort_by_color and sort_folder_contents, though it does not explicitly name or contrast those alternatives.

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 no guidance on when to use this tool versus sort_by_color, sort_folder_contents, arrange, or other layout tools. The only usage-related detail is the default behavior of leaving page 1 alone.

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

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

With no annotations, the description carries the full burden and does disclose real state-change behavior: the color ordering, that folders and widgets are moved ahead, and that page 1 is untouched by default. It omits whether the change is applied immediately or to a draft (siblings apply/reset_draft/diff/render_preview suggest a draft workflow) and whether it is reversible via undo, which matters for a mutation tool.

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

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

Three short sentences, each carrying distinct information (ordering rule, folder/widget precedence, page-1 default), with the core purpose front-loaded. No filler.

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

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

An output schema exists so return values need no explanation, and the ordering semantics are well covered. However, for a mutation tool with zero annotations, the description should say whether it applies immediately or stages a draft and whether undo restores the prior layout — that gap keeps it at minimum-viable completeness.

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

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

Schema coverage is 0%, so the description must explain the lone parameter — and it does: 'Page 1 is left alone by default' directly explains keep_first_page and its default value of true. It could go one step further and state what happens when the flag is false, but the meaning is clear.

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 ('Rainbow-sort') plus the exact resource and scope ('loose apps'), and spells out the resulting order (red -> purple, then white/gray/black). The word 'loose' plus 'folders and widgets go first' cleanly separates it from siblings like sort_folder_contents and sort_alphabetically.

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 the tool applies (color-based reordering of loose apps) and notes the default page-1 behavior, but never explicitly contrasts it with sort_alphabetically or says when a caller should prefer one over the other. Usage is inferable rather than stated.

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

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

No annotations at all, so the description carries the full burden and delivers almost nothing: it does not say this is a mutating reorder, whether it is undoable (an undo sibling exists), whether it affects all folders or only the current one, or what permissions it needs. The phrase "inside every folder" is the only real behavioral signal — scope — which lifts it above a 1.

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?

It is short, but this is under-specification rather than conciseness — a five-word fragment that front-loads nothing and omits the verb entirely. Length is fine; content density is not.

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

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

An output schema exists, so return values need not be explained, but for an unannotated mutation tool the description should still cover reversibility, scope, and side effects. None of that is present, leaving the agent to guess.

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

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

The tool takes zero parameters, so baseline is 4; there is nothing the description could add. It does at least confirm the operation applies across every folder rather than a specified one.

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?

"A-Z inside every folder" largely restates the name: sort_folder_contents becomes "A-Z" plus "inside every folder." There is no verb (sort, order, arrange) and no differentiation from the sibling sort_alphabetically, so an agent cannot tell which of the two it should pick.

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

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

No when-to-use, when-not-to-use, or prerequisite information is given. With sort_alphabetically sitting right next to it in the sibling list, the absence of any routing guidance is a real gap.

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

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

No annotations, so the description carries the full behavioral burden for a mutation, yet it says nothing about what happens on failure, whether cross-page/cross-folder swaps are allowed, or that undo/redo can reverse it. Only 'trade the places' hints at atomicity.

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 short, front-loaded sentence with no filler, but the brevity comes at the cost of substance rather than from compression — there is no structure beyond the single clause.

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

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

An output schema exists, so return values needn't be explained, but for a two-required-parameter mutation with zero annotation and zero parameter-schema coverage the description leaves out identifier format, validity constraints, and side effects. Given the complexity of the surrounding toolset, this is under-specified.

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

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

Schema description coverage is 0% and the parameters are named only 'a' and 'b' with titles 'A' and 'B'. The description's phrase 'two items' adds minimal meaning — it does not say whether each value is an ID, label, or index, which is the key ambiguity for this call.

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 (trade places) and a stated scope (two items), which distinguishes it from rearrange-style siblings like move or place_at. However, "items" stays vague — in a layout-editor toolset it is unclear whether these are apps, folders, or pages.

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 indication of when to prefer swap over move, place_at, arrange, or page_op, and no preconditions (same page, same folder, same type). The agent must infer the selection rule entirely from the sibling list.

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

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

No annotations are provided, so the description carries the full behavioral burden and does very little with it. It does not say whether undo is single-level or multi-level, whether the undone edit can be recovered via redo, or what happens when there is nothing to undo.

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 short, front-loaded sentence with no filler or redundancy. Nothing is buried or repeated.

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

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

An output schema exists, so return values need not be described, and the zero-parameter schema needs no explanation. However, for a mutation-style tool with no annotations, the description omits failure conditions and the undo/redo relationship, which an agent would need to call it confidently.

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

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

The tool takes zero parameters, so the description has no parameter semantics to compensate for and the baseline of 4 applies. Nothing in the text misrepresents the empty 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?

A specific verb (undo) plus a scoped resource (the last draft edit), so the agent knows this reverts a single prior change rather than a whole document. It does not explicitly distinguish itself from siblings like redo or reset_draft, which would be the final step to a 5.

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

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

Usage is only implied: an agent should call it after an unwanted draft edit. There is no statement of when not to call it, or that redo is the counterpart for re-applying an undone change, leaving the agent to infer routing among undo/redo/reset_draft.

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