opointo

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds valuable context: it never reads or rewrites existing source, and the sole existing-file edit is returned as a line to add rather than a file to overwrite. The 'PAID' flag also discloses a cost dimension not present in annotations.

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

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

Three sentences with no filler: the first identifies the action and outputs, the second explains the manifest mechanism, and the third clarifies the non-destructive edit behavior. The key constraints are front-loaded.

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

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

Even without an output schema, the description tells the agent what the tool produces: a screen file, a route, a registration line, and navigation instructions. It also explains the read-only edit model, so an agent has enough context 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 100%, so the schema already documents all four parameters, including the tab/root distinction and the compositionId meaning. The description does not add parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: it adds one new screen to an already-exported app, and enumerates the concrete deliverables: screen file, route, registration line, and navigation. The 'already exported' qualifier and manifest-reading behavior distinguish it from siblings like emit_screen.

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

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

Gives a clear condition for use: the app must already be exported and the .opointo/files.json manifest is required. It implies this is for post-export screen additions rather than initial generation, but it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only, it never touches the repo.' It goes beyond annotations by disclosing the heuristic nature ('A heuristic text scan, not a structural guarantee'), which is crucial for managing expectations about false positives/negatives. This is valuable additional context that annotations cannot convey.

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

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

Two sentences with no waste. The main purpose and specific problem list are front-loaded, followed by read-only and heuristic caveats. Every word earns its place; the structure is ideal for an agent to quickly grasp what the tool does and its limitations.

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 single-parameter tool with annotations covering safety and idempotency, the description covers the purpose, the list of problems, and the read-only/heuristic nature. The only minor gap is that it does not specify the return format (e.g., a list of problems with locations), but since there is no output schema, an agent might wonder about the exact shape of the result. This is a small omission given the tool's narrow scope.

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

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

The schema has 100% coverage: the single parameter 'code' is described as 'the TSX snippet to check.' The tool description adds context that the code should use 'these components' and what it checks for, but it does not add syntax, format, or edge-case details about the parameter beyond what the schema already provides. With full schema coverage, the description does not need to compensate, so a 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 clear verb ('Takes TSX... returns the glass-safety problems'), identifies the specific resource (TSX using these components), and enumerates the exact problems it detects (animated opacity, flex:1 collapse, clipped lens, conditional mount). It distinguishes itself from sibling tools by focusing on this narrow bug-checking task rather than component management or emission.

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

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

The description implies usage context—it is a heuristic text scan, not a structural guarantee—but it does not explicitly state when to use this tool over alternatives like verify_app or get_rules, nor does it mention any exclusions or prerequisites (e.g., 'use this for a quick check; for a definitive analysis, use verify_app'). The guidance is implicit, not explicit.

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

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

Adds substantial context beyond the annotations: the paid nature, the recipe-style output with exact files and paths, dependency install line, ordered steps, and verification behavior. This fully discloses what the agent should expect without contradicting readOnlyHint or idempotentHint.

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

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

Four sentences, each carrying distinct information: paid status, core purpose, return format, and prerequisite. It is dense and front-loaded with the most important facts, with no filler.

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

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

For a tool with no output schema, the description explains the generated recipe, file targeting, dependency installation, and how verify_app relates. The only notable gap is not explicitly separating this from emit_screen, but the whole-app scope is sufficiently clear for correct invocation.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description only reiterates that appId is the share code, which the schema already says, and adds no new meaning for the override parameter.

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

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

States a specific action and resource: it turns an opointo canvas into a working Expo app, with concrete deliverables. It does not explicitly contrast itself with sibling emit_screen, but the whole-app scope is clear from the title and description.

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 important preconditions: it is paid and requires a share code from the App Builder. However, it never explicitly states when to use this tool versus emit_screen or add_screen, so usage guidance is mostly implied rather than directly 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 provide readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds value by noting it is PAID, returns the complete file inline, lists components to install, and gives mounting instructions – important behavioral details not captured in annotations.

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

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

Three sentences with no waste. The PAID marker is front-loaded, the core purpose is stated first, and the sibling alternative and prerequisite are given succinctly. Structure is logical and scannable.

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-screen emission tool with no output schema, the description covers the return contents (file, components, mounting) and the required input. It doesn't detail error cases or edge limitations, but given the simplicity and schema completeness, it is largely sufficient.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description adds meaning by clarifying that compositionId is the 'share code' and explaining the output includes file, components, and mounting, which enriches understanding of how parameters drive the result.

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

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

The description clearly states the verb 'emit' (turns into a TSX file) and the resource (one composed screen), and immediately contrasts with the sibling tool emit_app for whole apps. This distinguishes it from alternatives without ambiguity.

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

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

It explicitly names emit_app as the matching tool for whole apps with navigation and a tab bar, implying this tool is for single screens. It also states the prerequisite of needing the share code from the App Builder, giving clear context for when to use it.

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

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

Annotations already cover the safety profile with readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: results are ranked, and the tool may deliberately return no catalog match but instead recommend the OS control.

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

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

Two sentences with no filler: the core behavior is front-loaded in the first sentence, and the actionable guidance is in the second. Every clause contributes value.

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

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

For a tool with one simple parameter and no output schema, the description adequately conveys input format, output type (ranked components), and the special fallback behavior. Nothing essential is missing for invoking 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?

The schema already documents the only parameter with a concrete example, and coverage is 100%. The description's 'plain language' phrase lightly reinforces natural-language input, but it does not materially add meaning beyond the schema.

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

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

The description starts with a concrete action and resource: takes a UI need in plain language and returns ranked components. It also highlights the distinctive fallback behavior — recommending the OS's own control when the catalog deliberately lacks an option — which separates it from siblings like list_components or get_component.

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

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

It gives clear usage context ('Useful before building a UI control by hand') that tells an agent when to reach for this tool. It does not explicitly name alternatives or state when not to use it, but the guidance is unambiguous for the common case.

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

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

The description discloses what the response contains (props with types/defaults/values, platform applicability, dependencies, runtime rules) and emphasizes the real consequence of violating rules. This adds value beyond the readOnlyHint and idempotentHint annotations, though exact output format is not specified.

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

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

Two focused sentences with no filler. The first sentence enumerates the content categories, and the second adds a high-value warning about rules causing a blank screen. Everything earns its place.

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

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

For a single-parameter, read-only retrieval with no output schema, the description names the major return categories and frames the tool's purpose well. It omits a precise return contract or slug-format details, but the stated content and example are sufficient for correct invocation.

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

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

Schema description coverage is 100%, with the single slug parameter documented and given an example. The description adds no additional parameter-level meaning, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as returning everything needed to write a correct call site for one component, including props, platform applicability, dependencies, and runtime rules. It is distinct from list_components and install_component, though it does not explicitly name sibling 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 gives clear usage context: use this when you need full details to write a correct call site for a single component, and it warns that runtime rules matter. It does not mention when not to use it or name alternatives, but the 'one component' framing implies the boundary.

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, so the safety profile is known. The description adds value by warning 'Getting it wrong fails at runtime, not at compile time' and explaining that the result depends on the components passed. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences with zero waste. It front-loads the core purpose ('The exact app-root provider nesting these components require'), then adds a crucial warning and a usage instruction. Every sentence earns its place, and the structure is clear and 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 simple tool with one optional parameter and no output schema, the description covers purpose, usage, and a behavioral warning. It doesn't describe the return format or error conditions, but given the tool's simplicity and the strong annotations, this is sufficient for an agent to use 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% because the parameter 'components' has a description: 'optional slugs in use.' The description reinforces this by saying 'Pass the components in use,' and clarifies that these are slugs identifying which providers are needed. This adds meaning beyond the schema's minimal description, so a 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 clearly states the tool returns 'the exact app-root provider nesting these components require, in the order that works.' This is specific about the resource (provider tree) and the action (get). It distinguishes from siblings like get_component or get_rules by focusing on provider nesting, so an agent can tell it apart without opening the schema.

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

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

It says to 'Pass the components in use to see which providers each one needs,' which gives clear usage context and indicates the tool is for when you have components and need the provider tree. However, it does not explicitly mention when NOT to use it or name alternative tools, so it lacks explicit 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations by explaining that these rules concern silent rendering failures, and noting the platform nuance ('on iOS, mostly native Liquid Glass'). This helps an agent understand the nature of the output without contradicting the annotations.

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

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

Three sentences, each with a distinct purpose: defining the resource, explaining parameter use, and providing usage context. No filler or redundant phrasing; information is front-loaded and scannable.

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

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

For a read-only, two-optional-parameter tool with no output schema, the description is largely complete. It explains what the rules are, how to filter them, and when to consult them. It could mention the return shape (e.g., a list of rule descriptions), but the concept is clear enough for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already explains that slug/platform are optional and what omitting them means. The description largely restates this ('Pass a slug to scope them to one component, and a platform to get only the rules that hold there'), adding slightly more specificity about scoping to one component, but not enough to exceed the baseline 3.

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

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

The description clearly identifies the resource ('runtime rules for this catalog') and defines what those rules are ('the mistakes that make a component render blank or wrong with no warning, no error and no red box'). This distinguishes it from sibling tools like get_component or list_components, which operate on components/tokens rather than on runtime rendering behavior.

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 explicit usage context: 'Relevant before writing animation or layout code around one of these components.' It also explains optional scoping via slug and platform. However, it does not explicitly mention when not to use the tool or name alternative tools for comparison, stopping short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read. The description adds value by noting the operation is 'FREE' (cost implication) and by specifying the content of the expanded step, which is not captured in the annotations. There is no contradiction.

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

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

The description is three sentences, all purposeful. It front-loads the key 'FREE.' and the core action, then explains the context and prerequisite. There is zero fluff, and every sentence earns its place.

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

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

For a read-only, idempotent tool with full schema coverage and strong annotations, the description is complete. It explains what the expanded step will contain, satisfying the lack of an output schema. The prerequisite of the same share code and step id is noted, so nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reiterates that appId is the share code and stepId is the step's id, but adds no new syntax or formatting beyond what the schema provides. It reinforces the relationship but does not compensate for any gaps because there are none.

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 ('Expands') and a specific resource ('one step of an emit_app recipe'), and enumerates exactly what detail is returned (full instruction, why it matters, how to know it worked, what to do when it didn't). It also explicitly contrasts with the short form returned by emit_app, distinguishing it from the sibling 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 description clearly states when to use the tool: when a step needs more detail, because emit_app returns steps in short form. It also notes the prerequisite of needing the same share code and step id. It does not explicitly name 'use emit_app for the initial list', but the context is implied and clear enough.

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 the operation read-only and idempotent, so the safety profile is covered. The description adds valuable behavioral context beyond that: the returned values are token names, not literal hex values, and selecting token names is what makes a retheme propagate. It also indicates the scope of the returned theme information.

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

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

Two sentences, with the core subject ('the theme system') front-loaded and the key token-name principle in a concise follow-up. Slightly cryptic phrasing like 'which hooks to call' costs a bit of clarity, but overall it is appropriately compact.

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 parameters and no output schema, the description carries the burden of explaining what the agent gets and how to use it. It lists the relevant scales, mentions the hooks, and provides the retheme propagation rule, which is enough for a simple read-only getter.

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 is nothing for the description to document. The baseline of 4 applies because the description still communicates the nature of the returned theme data, which is the only semantic detail that matters here.

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

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

The description clearly ties the tool to the theme system and names the concrete content it surfaces: hooks to call and the spacing, radius, and typography scales. The title reinforces the 'get theme tokens' verb-resource relationship, and it is distinct from sibling getters like get_rules or get_provider_tree, though it doesn't explicitly contrast itself with them.

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

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

Usage is implied rather than stated: an agent can infer this tool is relevant when working with theme tokens or retheming, especially since the description emphasizes token names over hex values. However, there is no explicit when-to-use guidance or comparison to alternative tools.

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

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

The description directly contradicts the readOnlyHint annotation: it states 'Adds one component to an existing project,' implying a mutation, while the annotation declares readOnlyHint=true. This is a serious inconsistency that misleads the agent about side effects. Furthermore, the description does not clarify whether the operation modifies the project file, and the 'PAID.' cost note is not a behavioral disclosure. The contradiction makes this dimension unacceptable.

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 with the purpose ('PAID. Adds one component...') and then lists the return payload in a compact list-like fashion. It is dense but not overly verbose, and each clause contributes information about behavior or output. The only minor issue is the lack of separation between purpose and caveats, but overall it is structured well.

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

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

Given the tool's complexity—returning a closure, files, provider nesting, and rules—the description thoroughly explains what the agent should expect as output. It also covers exceptions like 'Foundation components need no licence key.' However, it does not mention prerequisites such as project existence or payment enforcement beyond 'PAID.', and the contradictory readOnlyHint muddies expectations. Still, the description is largely complete for invoking the tool correctly.

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

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

The single parameter 'slug' is fully covered by the schema with an informative description ('the component slug, e.g. "button" or "bottom-sheet"'). The tool description adds no additional meaning about the parameter beyond the schema, so it meets the baseline for 100% coverage. No extra semantic value is provided.

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

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

The description clearly states the tool's action: 'Adds one component to an existing project.' This is a specific verb and resource, and it differentiates from siblings like get_component or list_components by emphasizing the install action and the transitive closure result. The distinction is explicit enough for an agent to select it correctly.

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 is given on when to use this tool versus alternative sibling tools. The only contextual hint is 'It replaces fetching /r/*.json by hand,' which is not a sibling tool and provides no exclusion criteria. There is no mention of when not to use it or how it relates to add_screen or emit_app. This leaves the agent to infer use cases.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description only needs to add context. It adds cost/latency ('Cheap'), output content (system vs. custom components), and the closed 'shipped' scope, which goes beyond the structured annotations without contradicting them.

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

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

Three sentences: purpose/fields, cost/usage context, and filter parameters. Everything earns its place and the core action is front-loaded.

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

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

For a simple list tool with two optional enum params, no required arguments, and no output schema, the description is complete: it states what is returned, that filtering exists, and that it's cheap. Nothing essential for a correct first call 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 0%, so the description carries the burden. It says both parameters are optional filters and relates tech to the iOS-system-vs-own-component distinction, but it does not explain what category/tech values mean or how the filters affect results; the enums remain underspecified.

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

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

The description opens with a specific verb and resource: 'Lists the shipped @opointo/ui components,' and names the returned fields (slug, purpose, category, rendering implementation). It is clear and informative, but it does not explicitly differentiate itself from siblings like get_component or find_component, relying on the list-all framing to separate 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?

It gives clear usage context with 'Cheap, and a good first call,' signaling when an agent should reach for it early in a workflow. It doesn't name alternatives or state when not to use it, so it falls short of a full when/when-not comparison.

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, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavior: it reads a specific file, flags changes needing code edits, and explicitly avoids touching customer screens. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences and front-loads the core purpose. Minor extras like 'PAID.' and the closing summary add slight fluff but do not obscure the key information. It is well-structured 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?

For a read-only reporting tool with three parameters and no output schema, the description covers the mechanism, scope, and parameter conditions. It does not specify the return structure, but given the read-only nature and the statement 'returns only what moved,' the agent has enough to call it. Internal terms like 'split-unverified' are referenced in parameter descriptions, so context is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds conditional usage for all three parameters: 'current' only when a split-unverified blocker asks, 'manifest' as the parsed files.json, and 'acceptSplit' only after customer agreement. This conditional context goes beyond the schema and is valuable for correct invocation.

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

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

The description clearly states the tool reports what changed in opointo-supplied files since export and returns only what moved, distinguishing it from siblings like install_component or get_component. The verb-resource pair ('reports changes in supplied files') is specific and unambiguous, and the closing line ('This is how the components and app shell we supplied stay current') reinforces the purpose.

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 the tool reads .opointo/files.json, requires no share code, works months later, and never touches customer screens—giving clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, leaving the agent to infer from sibling names.

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 mark it as read-only, idempotent, and non-destructive; the description adds detailed behavioral context by listing the specific checks performed and results returned, such as missing files, altered copy-verbatim files, absent packages, config merge status, and Xcode build viability. It does not specify exact output shape, but the enumerated checks are sufficient for an agent to know what to expect.

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

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

Three sentences, each with a distinct job: statement of purpose, input/output mapping, and value. The list-heavy middle sentence is dense but not bloated, and the opening 'PAID' is a necessary cost disclosure. The description is well 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?

Given no output schema, the description usefully enumerates the returned categories and states the required inputs at a conceptual level. It does not specify exact output formatting or error behavior, but the schema covers parameter constraints and the tool's scope is clear.

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

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

The description groups the parameters into high-level categories ('file paths with byte sizes, package.json dependencies, project config, build toolchain'), but it adds little beyond the schema, which already documents details like byte sizes, relative paths, and installed versions. With 60% schema coverage, the prose only partially compensates and omits the appId parameter.

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

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

The first sentence states a specific action and object: 'Checks that an emitted app was applied correctly, before it is built.' This clearly distinguishes verify_app from emit_app and the other sibling tools, and the description enumerates the concrete verification dimensions.

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 explicit timing ('before it is built') and intent ('applied correctly'), so an agent knows when to invoke it. It does not explicitly name an alternative or say when not to use it, so it stops short of a 5.

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