recipebooq

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

Adds real context beyond the annotations: subscription gating, the guarantee that existing files are never rewritten, and mode-dependent outputs (screen file + mounting route + registration line vs. a standalone file). These details clarify that 'add' produces artifacts rather than mutating state, consistent with readOnlyHint=true.

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 subscription prerequisite first. The telegraphic, clause-fragmented style ('With the project's... Without it...') is efficient but slightly disjointed to parse.

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

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

With no output schema, the description carries the return-value burden and does explain the two possible outputs and the no-rewrite guarantee. It stops short of spelling out the route/registration payload structure, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already explains appId, screen, manifest, tab, and componentName. The description adds mode context around 'manifest' but no per-parameter syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: adds one Architect-designed screen to a project, and distinguishes the two output modes (manifest-aware vs. self-contained Expo file). However, it never differentiates from sibling tools like propose_screen or emit_app, which could plausibly be confused with this 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?

Gives a prerequisite ('Needs a subscription') and describes the two execution contexts (with vs. without the project's .opointo/files.json), but never says when to choose this over propose_screen or emit_app. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds genuine value beyond them by clarifying it is a 'read-only text scan, not a guarantee' and therefore best-effort rather than exhaustive — a limitation an agent would otherwise not know.

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

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

Two tight sentences, front-loaded with the bug classes and closed with the scope caveat and sibling routing. No sentence is filler.

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

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

With no output schema, the description correctly conveys expected findings (blank renders with no error) and sets expectations that results are heuristic, not guaranteed. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter ('code', 'the TSX to check'), so the schema already carries the semantics. The description adds nothing about the input format or size limits, so the baseline 3 applies.

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

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

States a specific verb ('Scans') and resource ('TSX that uses these components') and enumerates the exact bug classes it detects. It is clearly distinguishable from verify_app, which it explicitly names as the project-wide alternative.

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 frames this as a narrow per-snippet check and routes whole-project validation to verify_app. It stops short of stating explicit exclusions or prerequisites (e.g. what happens if the snippet lacks these components), so it is strong but not 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?

Adds substantial context beyond the annotations: an entitlement requirement, a daily allowance quota, and the notable fact that single-step fetches don't count against that quota. It also discloses the return shape (files with target paths, one install line, ordered steps with a check each), which is exactly what an agent needs given 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?

Three tight sentences, front-loaded with the prerequisite and the core action, then the return format, then the parameter tip. No filler.

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

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

With no output schema, the description carries the return-value burden and does so precisely, and it covers the quota and prerequisite behavior an agent needs before calling. Nothing material is missing for a read-only recipe generator.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that `step` fetches one step in full and is quota-exempt, which the schema does not say. `page` and `override` semantics are left to the schema.

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

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

States a specific verb and resource: turns an Architect design into a working Expo app (navigation, providers, tab bar, screens, components) and returns a per-project recipe. This clearly separates it from siblings like propose_app, add_screen and verify_app, though it never names an alternative explicitly.

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

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

Gives a prerequisite ('Needs a subscription') and one concrete usage mode ('Pass `step` for one step in full'), but never says when to choose this over propose_app/verify_app or when emission is inappropriate. Usage is implied by the flow rather than spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value the annotations cannot: results are ranked, and the catalog may intentionally return nothing when the platform's native control is preferable — a non-obvious negative-result contract.

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 front-loaded sentences with no filler, leading with what the tool does and the ranking behavior before the omit-need shortcut. Slightly dense phrasing ('ships nothing on purpose') but every clause earns its place.

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

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

With no output schema, the description usefully sketches what comes back (ranked components, purpose text, whether a real system control renders). The only notable gap is the unexplained `category` enum, which the schema also fails to document.

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

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

Schema description coverage is 50%, and the description only compensates for `need` (omit it to list all). The `category` enum (controls/chrome/surfaces) is left entirely undefined in both schema and description, so the agent must guess what those buckets mean.

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 ('Finds the component') scoped to a plain-language UI need, and adds the distinctive behavior of ranked results plus deliberate-absence signaling. It implicitly separates itself from the id-lookup sibling (get_component) but never names it, so differentiation is inferential rather than explicit.

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

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

The description gives one concrete usage rule: omitting `need` lists every component with purpose and system-control status. Beyond that it offers no when-to-use versus alternatives guidance or prerequisites for the ranked search path.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered and the description need not repeat it. It adds only that results are scoped per topic and are conceptual guidance rather than live state. No error, pagination, or freshness behavior is disclosed.

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

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

The single sentence opens with the fragment 'How an app is set up so these components work and follow its theme, one topic at a time:', which is not a clause and delays the actionable content. The enumerated topics arrive only after a heavy preamble, so the definition is not front-loaded and reads awkwardly.

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

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

With no output schema, the description carries the burden of describing return content, and it does so for all three topics. The emit_app note gives useful context about when the setup is already wired. Only the platform-scoping behavior for 'rules' is undocumented.

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

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

Schema coverage is only 50%, so the description must compensate — and it does for the required 'topic' parameter by explaining what each of the three enum values yields (providers/theme/rules). The optional 'platform' parameter's 'rules only' constraint is left entirely to the schema, which is the remaining 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?

The description names the resource (app setup guidance) and enumerates the three concrete outputs — app-root providers in working order, theme hooks and token scales, or catalog-wide rules — so an agent knows what each topic returns. The verb is buried ('How an app is set up...'), but the content is specific enough to separate it from siblings like get_component or find_component. It stops short of explicitly contrasting with those 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?

Usage is implied rather than stated: 'one topic at a time' and the enum values tell the agent how to call it, and 'An app built by emit_app already has all three wired' hints that the tool may be redundant after emit_app. There is no explicit when-to-use/when-not rule or named alternative for looking up component details, so guidance stays inferential.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the shape of the response, per-platform rendering differences, required root providers, and 'runtime rules that stop it rendering blank' — useful for an agent deciding whether the call is sufficient.

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, front-loaded sentence that lists exactly what comes back with no filler. Slightly list-like and could be scannable as bullets, but every clause earns its place.

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

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

With no output schema, the description carries the full burden of describing the return payload and does so thoroughly — props, defaults, allowed values, platform rendering, providers, dependencies and runtime rules. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and the description adds no information about slug or platform beyond the schema (the enum and 'only the rules that hold there' note live in the schema itself). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a clear resource and scope: it returns everything needed to write a call site for one component, enumerating props/types/defaults, platform rendering, providers, dependencies and runtime rules. An agent can distinguish it from find_component (discovery) and install_component (mutation/installation), though no sibling is named explicitly.

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

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

The framing 'everything needed to write a correct call site' implies pre-use before installing or emitting a component, but there is no explicit when-to-use, when-not-to-use, or named alternative such as find_component. Usage is implied 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?

Annotations already richly declare the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds a genuine auth-type precondition (subscription requirement) and describes the deliverables, but the 'Adds one component to an existing project' framing sits in mild tension with readOnlyHint=true, creating some ambiguity rather than fully clarifying behavior.

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

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

Three dense sentences with essentially no filler; every clause carries information. The only structural nit is that it front-loads the subscription precondition rather than the core purpose, and the deliverable list is tightly packed, but it remains efficient.

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 single-parameter, no-output-schema tool with rich annotations, the description is complete: it covers the precondition, the mutation-free generative output (files, install order, target paths, install line, providers, runtime rules), and the recipe-id branch. The only missing piece, sibling routing, is already penalized under usage guidelines.

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

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

Schema description coverage is 100% and the single slug parameter is already documented with both examples ('button' and a recipe id such as 'supabase'). The description's note that a backend recipe id 'adds that integration' with its own files and per-app wiring adds modest meaning beyond the schema, but largely echoes the schema's own example, so the high-coverage baseline of 3 is appropriate.

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

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

The description states a specific verb and resource — it 'adds one component to an existing project' — and details exactly what that yields (files in install order with target paths, the install line, providers, runtime rules), plus the recipe-id variant. It is clear on its own but never explicitly distinguishes itself from siblings like get_component, find_component, or add_screen, so it stops short of a 5.

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

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

The only eligibility guidance is the precondition 'Needs a subscription, except for the free foundation components,' which acts as a partial when-not gate. There is no explicit routing guidance telling the agent when to pick install_component over get_component/find_component or add_screen, so usage is only implied.

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

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

Annotations only say readOnly=false, idempotent=false, destructive=false, openWorld=false. The description adds genuinely useful context beyond that: a link is returned, it opens as a NEW UNSAVED design, the person edits every screen, and dryRun avoids creating a link. It stops short of explaining what happens to prior proposals or how 'into' merges into an existing design, but it does substantially more than 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 core meaning is buried in one long run-on sentence followed by fragments such as 'into: the code in the person's line' and a dangling 'or with app: { version: 1 } a short plan's.' The propose-then-hand-back flow is not front-loaded, and stray quotation marks around 'photos' make the format options harder to parse than the schema alone.

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 complex tool: a deeply nested AppSpec object, four parameters, no output schema, and write semantics. The description covers the return value (a link), the dryRun escape hatch, and the propose/emit_app lifecycle, which is the critical part. It leaves into's merge behavior and the exact format string values murky, so it is adequate but not complete for a tool of this 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 50%: app and dryRun are documented in the schema, while into and format are bare. The description attempts to cover both gaps, saying into lands the design 'in their open design' and format: true returns the format and every block or 'photos' for sample photos. The into explanation is garbled ('the code in the person's line') and the format variants are only partly legible, so it compensates but not cleanly.

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?

It states a specific verb and resource: send an AppSpec and get back a link that opens it in the Architect as a new, unsaved design. It also distinguishes itself from emit_app by noting the person 'hands it back for emit_app', which clarifies the propose-vs-commit split. Verbose framing aside, an agent can tell what it does and how it differs from the sibling that commits the design.

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 propose-then-emit_app flow is described, which implies when to use this tool, and dryRun is explained as a way to check without making a link. However, there is no explicit 'use this when X, use emit_app when Y' statement, and the guidance is embedded inside a run-on sentence rather than stated as a rule an agent can act on directly.

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

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

Adds real context beyond annotations: the result is a new, unsaved design the person can edit, which tells the agent nothing is persisted or destroyed (consistent with destructiveHint=false). It also discloses the dryRun non-effect, though it says nothing about permissions or failure behavior.

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

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

The purpose and the propose_app alternative are front-loaded, but sentences are long run-ons and the 'into: as propose_app's.' fragment adds noise rather than information. Short overall, but not 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?

Given four params, nested composition objects, and no output schema, the description covers the essentials: what to send, what comes back (a link), and how to preview without a link. It leaves gaps on 'into', the exact shape of the dryRun report, and error behavior.

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

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

Schema coverage is 50%, so the description must compensate for undocumented params. It does add meaning for 'format' ('true returns the format') and echoes dryRun, but 'into' is reduced to the unusable fragment 'as propose_app's,' leaving one of four params effectively unexplained in both places.

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 ('design a single screen'), explains the input format and the return value (a link opening a new, unsaved design in the Architect). It explicitly distinguishes itself from propose_app for whole apps, so an agent can route correctly despite the garbled 'into: as propose_app's' fragment.

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?

'For a whole app, use propose_app' is an explicit alternative with the selecting condition. The dryRun and format flags are also framed as usage choices ('checks without making a link', 'returns the format'), though 'into' gets no usable guidance at all.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: it names the file it reads, scopes the output to changed opointo-supplied files, guarantees it never touches the customer's own screens, and discloses the flagging behavior for changes needing a code edit rather than a copy.

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, no filler, with the subscription prerequisite front-loaded before the core behavior. Information is well ordered and each sentence carries a distinct point (precondition, mechanism/benefit, scope guarantee).

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

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

With no output schema, the description usefully explains what is returned (only changed opointo-supplied files) and the flagging outcome. Given 100% schema coverage and explicit annotations, the remaining gap is only the absence of named sibling alternatives, which is minor for a four-parameter tool with nested objects.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including their conditional triggers. The description adds no syntax or format detail beyond the schema (it only restates the manifest concept as .opointo/files.json), so the baseline 3 applies.

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

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

The description states a concrete verb and resource: it reads the project's .opointo/files.json and returns the opointo-supplied files that changed since export. That is clear and disambiguates the misleadingly named 'update' tool (which is actually a read), but it never names a sibling (install_component, get_component, verify_app) to differentiate itself explicitly.

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

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

It gives a precondition ('Needs a subscription') and a benefit context ('works months later with no share code'), and the schema params carry conditional triggers ('only when the answer's page.next asks for it'). However, there is no explicit statement of when to choose this over the sibling tools, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a genuine non-annotation fact, the subscription requirement, plus the fact that it inspects the locally installed Xcode/fingerprints. It does not say whether the tool returns a report or fails on mismatch, which for a verification tool is a meaningful behavioral 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?

A prerequisite clause plus one dense sentence listing the checks, with no filler. The enumeration is long but every item is informative; the leading 'Needs a subscription' is slightly awkward as an opener but is useful information.

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

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

For a 5-parameter tool with nested objects and no output schema, the description explains the scope of checks but not what the agent gets back (pass/fail list, diagnostics, error behavior) or how files/appId must be assembled. The missing return-shape information is the main gap, since no output schema exists to cover 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?

At 60% schema coverage the schema carries most of the burden, documenting appId, files[].path/bytes/sha, and several nested config/toolchain fields. The description never mentions a parameter by name, though its list of checks maps loosely onto the groups (files, dependencies, toolchain.xcode). No additional format or usage meaning is supplied.

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 ('checks') and resource ('an emitted app before it is built'), then enumerates exactly what is validated: missing files, altered verbatim files, absent packages, expo-router config merge, Xcode buildability, and native-build need. That enumeration distinguishes it clearly from siblings like emit_app, propose_app, or get_app_setup.

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?

'before it is built' pins the point in the workflow when this tool applies, and 'Needs a subscription' flags a prerequisite up front. It stops short of naming an explicit alternative (e.g. 'use get_app_setup for runtime config inspection') or stating when not to call it.

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