Refcat

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds little beyond confirming it is a catalog lookup — no mention of not-found behavior, caching, or scope — which is acceptable given complete 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 tight sentences with the purpose front-loaded, followed by the parameter hint and then the sibling routing. Nothing is redundant or padded.

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

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

For a single-parameter read with full annotations and no output schema, this covers what an agent needs to call it correctly, including the slug flexibility. The one gap is that 'metadata' is never qualified — which fields come back is left unknown, though the low-stakes read nature makes that minor.

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 carry the parameter burden, and it does: it clarifies that appId may be either an ID or a human-readable slug such as 'spotify'. That is real added meaning the bare 'string' schema lacks; it stops short of saying where to obtain a valid ID.

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

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

States a specific verb+resource ('Metadata for one app in the catalog') and the scoping word 'one' distinguishes it from list_apps/search_apps. An agent can tell immediately this is a single-entity lookup, not a search.

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

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

Explicitly routes to the sibling get_app_flows for flow data, which gives a clear when-to-use-this-instead signal. It does not say when to prefer list_apps or search_apps over this when the ID/name is unknown, so the exclusion side is only partial.

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/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered, each carries a capture date, and large apps require paging because hundreds of flows may exist.

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

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

Three short sentences, front-loaded with the resource and scope, then pagination guidance, then the natural next tool. 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 3-parameter read tool with no output schema, the description covers ordering, pagination, and the follow-up call adequately. Only the limit parameter's meaning is unaddressed, a minor omission given schema bounds are explicit.

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

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

Schema coverage is only 33% (offset only), so the description must compensate. It does add that appId also accepts a slug and that offset drives pagination, but limit's default/max semantics are left entirely to the schema, leaving a partial 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 and resource — the ordered list of flows for one app — and illustrates what a flow is (onboarding, checkout, settings). It is clearly distinguishable from get_flow (single flow steps) and search_flows, which it does not overlap with.

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

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

Explicitly routes the agent: page with offset for big apps, then call get_flow for the steps of one. It gives clear context and a named follow-up, though it does not contrast with search_flows for filtered lookups.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful context beyond annotations by noting the HTML includes tables, font fallbacks, and dark mode, and by mentioning the Pro/free-flows availability condition.

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-loads the key resource and source. Every fragment contributes useful information about what the HTML contains, why to use it, and availability, with no 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 simple one-parameter, read-only retrieval tool with rich annotations and full schema coverage, the description provides enough context to call it correctly. The only minor gap is that the availability phrase 'Pro, or this week's free flows' is terse and not fully explained.

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?

There is only one parameter and schema description coverage is 100%, so the schema already documents emailId as coming from search_emails. The description reinforces that source but does not add further meaning such as format, validation, or lookup behavior, so the 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 resource as the original HTML of one email from search_emails, which distinguishes it from the sibling search tool. It is specific about scope and content, though the action verb is only implied by the tool name rather than stated in the description itself.

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 clear use case: adapt the retrieved HTML to the user's brand instead of writing email HTML from scratch. It also implies the prerequisite that the emailId comes from search_emails, but it does not explicitly state when not to use it or detail other alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description goes beyond them with genuinely useful context: a concrete payload-size warning ("tens of thousands of tokens for a long flow" with elements), the default compact field set, and the hook into get_screen via screenDocId. It stops short of describing pagination or flow-size limits, but the cost disclosure is the operationally important piece.

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

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

Three short sentences, front-loaded with the result shape, then the default output fields, then the opt-in expansions with their cost caveat. No filler and no repetition of what the schema already declares.

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 only two parameters and no output schema, the description is nearly self-sufficient: it enumerates the compact return fields (screenDocId, pageType, patterns, components, keyTexts), the optional additions, and the cost tradeoff. The remaining omission is provenance for the required flowId.

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 has to carry the semantics, and it does for include — both enum values are explained concretely (OCR/hotspot boxes per step vs. step links) along with the default-empty behavior. flowId is only implied by "One flow"; the description never says what it is or where to obtain one, which is the one real 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?

"One flow with every step in order" states the resource (a single flow), the shape of the result (all steps, ordered), and implicitly distinguishes itself from the plural/list siblings get_app_flows and search_flows. An agent can tell this is a fetch-by-id tool rather than a search tool 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 gives clear conditional usage for the include parameter ("compact by default", elements adds boxes, connections adds links) and cross-references get_screen for screenDocId. However it never states when to call this versus get_app_flows or search_flows, or that a flowId must first be obtained from a list/search call — the caller must infer the navigation path from the sibling name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine value by describing the return shape (capture date, screen count, up to 3 preview images per entry), which no output schema provides.

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 that front-loads the object (earlier captures of the same flow) and then lists payload contents. No filler, nothing redundant.

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

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

For a simple one-parameter read tool with rich annotations and no output schema, the description covers purpose and return contents adequately. Missing only minor operational details such as ordering, count limits, or whether history is truncated.

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 flowId parameter is never mentioned in the description. "The same flow" hints that a flow identifier is needed, but format, whether it accepts names or IDs, and required-ness are left entirely to the caller.

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 a specific resource — earlier captures of a given flow over time — and enumerates what each entry contains (date, screen count, preview images). It implicitly distinguishes itself from get_flow by emphasizing "earlier captures," though it never names the sibling explicitly.

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

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

Usage is only implied by "how it changed over time"; there is no explicit statement of when to call this instead of get_flow, get_app_flows, or search_flows. An agent can infer the versioning use case but gets no guidance on prerequisites 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about the returned composition, but does not cover error behavior, permissions, or how missing projects are handled.

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 no wasted words. However, it is so terse that it omits the retrieval verb and any parameter context, making concision come at the cost of 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?

With no output schema, the description should carry more burden. It states what the project contains but does not explain projectId usage, return shape beyond a list of contents, error cases, or how it relates to list_projects.

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 only parameter, projectId, is neither described in the schema nor mentioned in the description. The agent can see it is required but has no semantic guidance beyond the name.

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 and return contents (screens, positions, connections), implying retrieval of a single project. But it lacks an explicit verb and does not directly distinguish itself from list_projects or sibling get_* tools beyond the singular noun.

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 guidance on when to use this tool versus list_projects, get_app, get_flow, or other siblings. The singular form implies fetching one known project, but the agent must infer this.

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 a safe, idempotent read, and the description goes well beyond them: it discloses the dual image/JSON return shape, the token cost of each image size (~1-2k for 'small'), the bbox normalization scheme and top-to-bottom sort order of elements, and the citation obligation. That is precisely the behavioral context annotations cannot express.

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

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

Front-loaded with the core statement, then layered detail on return format and image sizing; every clause carries information. The long parenthetical about bbox and sorting is dense but earns its space, and nothing is repeated from the schema verbatim.

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 takes on the full burden of describing return values and does so thoroughly, including image sizing trade-offs. The only gap is the untied `includeElements` flag, which an agent must guess toggles the elements payload described in the text.

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 carry parameter meaning; it fully explains the `image` enum ('small' ~800px/~1-2k tokens, 'full' 1800px) and implies what `elements` contains. However, `includeElements` and `screenDocId` are never explicitly addressed, so coverage of the three parameters is only partial.

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

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

The opening sentence names a specific verb and resource ('One catalog screen with its image and structure'), making clear this is a single-record fetch. It contrasts implicitly with the search_* siblings via the word 'One', but never names an alternative, so an agent must infer the retrieval-vs-search split.

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 conveyed only through downstream instructions ('look at it for color, typography and spacing', 'use them to reproduce hierarchy'), not through call-selection guidance. There is no statement of when to prefer get_screen over search_screens/search_screens_by_image or what a caller needs (a screenDocId from a search) to invoke 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description's note that platform `email` returns brands with email galleries is a useful semantic nuance, but it largely duplicates the schema's enum description and says nothing about pagination limits or result shape.

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

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

Two compact clauses with no filler, and the optional-filter framing is front-loaded. The sentence fragment opening costs a little polish but nothing is wasted.

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

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

For a read-only, no-required-parameter listing tool with annotations covering the safety profile, this is close to sufficient. The notable remaining gap is that no output schema exists and the description never hints at what fields an 'app' object contains or how results are ordered.

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%: `offset` and `platform` are documented in the schema, while `limit` and `category` have no descriptions. The description compensates for `category` by pointing to list_categories, but `limit` (default 24, max 48) is left entirely to the schema and the pagination behavior with `offset` is 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 the resource (apps in the catalog) and the two optional filters (category key, platform), which is enough to distinguish a plain listing from search_apps or similar_apps. It is slightly telegraphic — 'Apps in the catalog' has no verb — but the intent 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?

It helpfully tells the agent where category keys come from ('from list_categories'), which is real routing guidance, and clarifies what platform `email` returns. However, it never states when to use this instead of the very similar sibling search_apps, nor any 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?

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds domain context that categories are platform-scoped and that emails, games, store listings, and ads have separate rails, but it does not disclose return format, ordering, or other behavioral details.

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 purpose and list_apps relationship. The second sentence about other rails is useful but slightly indirect, and the phrase 'with the key list_apps filters by' is a bit awkward.

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

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

For a simple read-only list tool with one optional enum parameter and no output schema, the description provides enough context: it says what the tool returns conceptually and how it relates to list_apps. It could be stronger by explicitly stating that the result is a list of categories, but the key usage context is present.

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 fully documents the single optional platform parameter with a 100% description coverage and an enum, including the Pro requirement for certain values. The description reiterates platform scoping but adds no parameter semantics beyond what the schema already provides, so the 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 identifies the resource as a platform's category rail and ties it to the keys that list_apps filters by, so an agent can infer it returns category/filter data. It also distinguishes this rail from dedicated email, game, store, and ad rails, though the metaphor 'rail' is less direct than 'list categories'.

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

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

The phrase 'with the key list_apps filters by' implies this tool should be used to discover filter keys before calling list_apps. However, there is no explicit when-to-use guidance, no mention of alternatives like list_facets, and no exclusions beyond noting that other domains have their own rails.

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: counts represent flows, and optional query/filters narrow every count including flowIntents. It does not detail response structure or whether counts are exact/permission-limited, but it adds meaningful value beyond 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, front-loaded with the core purpose and return content, followed by usage guidance and parameter behavior. No 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?

Given the nested filter schema, absence of an output schema, and read-only annotations, the description provides enough context to select and invoke the tool. It could be more complete by explaining the response shape or query semantics, but the essentials are present.

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?

Top-level schema coverage is low, so the description should compensate. It explains that query/filters narrow counts and that flowIntents is affected, but it does not clarify what query searches or how filters combine. Nested filter descriptions in the schema partially fill the gap, so this is adequate but incomplete.

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

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

States a specific resource and return content: filter vocabulary with real counts (number of flows) for named dimensions. It clearly distinguishes itself from search_screens and search_flows by positioning itself as the facet-discovery step before filtering.

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 instructs: 'Call this before filtering search_screens or search_flows so filters are real values, not guesses.' This names the alternatives and the condition under which to use this tool, leaving little ambiguity.

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

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

Annotations already declare this as a safe, read-only, idempotent, non-destructive operation. The description usefully adds that results are scoped to the caller and returned newest first, but it does not describe pagination, empty results, or what fields a project contains. With annotations covering the safety profile, this is a modest but real addition.

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 phrase with no filler, and the most useful qualifiers (caller scope, newest-first ordering) are front-loaded. For a zero-parameter list tool, this is appropriately sized.

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

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

The tool is simple with no parameters and no output schema, so the description does not need to explain parameter usage. However, because there is no output schema, the description should ideally say more about the return shape or pagination behavior, and it leaves 'projects' undefined. It is minimally adequate but not complete.

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

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

The tool has zero parameters, so there are no parameter semantics to document and the baseline is 4. The description does not need to compensate for any schema gap, though it could mention whether pagination is intrinsic.

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 ('projects') and adds two useful qualifiers: scope ('caller's') and ordering ('newest first'). However, it never explicitly states the verb 'list' and does not differentiate it from the singular sibling get_project or clarify what a project is in this domain. The purpose is inferable but not sharply stated.

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

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

There is no guidance on when to use this tool rather than get_project, list_apps, or search_apps. The only implied usage cue is the caller-scoped collection, but no alternatives or exclusions are named.

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 openWorldHint=false, so the safety and read-only profile is fully covered. The description adds no behavior of its own — nothing about result ordering/relevance, whether matching is fuzzy or exact, or that some platforms require Pro (that constraint lives only in the schema).

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

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

A single front-loaded sentence with the verb, resource, and match dimensions stated immediately, followed by illustrative examples. Nothing is wasted and nothing important is buried.

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

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

For a simple read-only search with no output schema, the description is serviceable but thin: it never says what a result contains, how results are ranked or truncated by limit, or whether the search is substring versus semantic. The agent can call it, but cannot predict the return 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?

Schema coverage is only 33%, but the gap is partially absorbed: platform carries its own enum documentation in the schema and limit has bounded defaults there. The description contributes real meaning only for query, clarifying that matching spans name, website, and theme — the other parameters get nothing beyond what the schema already says.

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

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

States a specific verb and resource ('Find apps in the catalog') and names the matchable dimensions (name, website, theme), with concrete examples that clarify the intent. It doesn't explicitly distinguish itself from list_apps or get_app, so an agent must infer that this is the free-text path versus enumerate-or-fetch.

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 examples imply the search context (free-text lookup by brand name, domain, or category), but there is no stated when-to-use versus list_apps/list_categories, and no note on falling back to get_app once a result is found. Usage is inferred rather than directed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value by disclosing the result granularity (one email per result with desktop and/or mobile image) and the hasHtml flag semantics, but says nothing about pagination behavior or result caps.

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

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

Three tight sentences with no filler; the core search behavior comes first, then the result shape, then the follow-up routing and prerequisite. 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 characterizes the return unit and the hasHtml signal, and names the follow-up tool. The remaining gap is that flow-intent filtering and pagination are never mentioned for a 5-parameter 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?

At 60% schema coverage the description maps 'by description' to query and 'by brand' to appId, which is useful. However flowIntents (a 15-value enum with no schema description) and limit are left unexplained, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource (search real product emails) plus the two search axes (description or brand) and what one result is. It does not contrast itself with the many sibling search_* tools (search_flows, search_screens), so an agent must infer the boundary, but the purpose itself 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?

Gives the prerequisite ('Needs Pro') and routes the agent forward: when hasHtml is true, call get_email_html to get the original HTML. It lacks an explicit when-not/alternative statement versus other search tools, which keeps it off a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral fact that results are whole flows without step detail, requiring get_flow to expand — useful context beyond the structured fields, though nothing is said about result volume or pagination 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?

Two tightly packed sentences with zero filler; the search scope is front-loaded and the follow-up instruction trails it appropriately.

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?

There is no output schema, but the description implies the shape of results (whole flows, no steps) and points to get_flow for detail, which is enough for correct invocation. Remaining gaps — result ordering, pagination across offset/limit — are minor for a read-only search.

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

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

Schema coverage is only 40%: platform and offset are described in-schema, but limit, query and flowIntents are not. The description partially compensates by saying search works 'by intent, app or description', mapping loosely to flowIntents and query, but it never mentions limit/pagination or that 'app' filtering is not a dedicated parameter — which could mislead an agent.

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 (Search) and resource (whole flows), and parenthetically defines a flow as 'ordered screen sequences', which disambiguates it from search_screens. It also names the follow-up sibling get_flow, so an agent can distinguish the two without opening either schema.

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

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

'Then get_flow for the steps' gives explicit sequencing guidance against the most likely alternative sibling. It does not state when NOT to use this tool (e.g., when to prefer get_app_flows or search_screens), so it falls 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 cover the read-only/idempotent/non-destructive profile, and the description adds genuinely new behavioral facts: return shape is per-screen metadata, and images are capped at 4 with an explicit ~1-2k token cost each. That cost disclosure is exactly the kind of thing annotations cannot express.

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

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

Three sentences, front-loaded with the search scope and examples, then returns, then the hand-off to get_screen. No filler and nothing buried.

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?

No output schema, so the description does step in with 'returns metadata per screen' plus the image-cost caveat, which is adequate for a search tool. What's missing is any mention of the filters object or plan-gated platforms, though the schema covers the latter.

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 40% schema coverage the description has to carry weight, and it does for the two parameters that matter most: 'query' is illustrated with three contrasting example inputs (free text, 'Spotify', 'linear.app'), and 'includeImages' is given a quantity cap and token cost that the schema's bare boolean does not convey. The large nested 'filters' object (six sub-properties, one with no schema description) is never mentioned, which is the main 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+resource ('Search individual UI screens') and immediately scopes what can be searched (description, app name, site) with three concrete example queries. It also explicitly contrasts with get_screen, so an agent can distinguish the discovery tool from the detail tool without opening a schema.

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

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

Gives clear context for opting into images ('set includeImages to also get the top screens as images') and routes the agent to get_screen when full structure is needed. It does not address when to prefer search_screens_by_image or similar_screens, which are the closest siblings, so routing is clear but not exclusive.

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 read-only, idempotent, non-destructive, which the description correctly does not repeat. Instead it adds real behavioral context: free-plan caps of 2 images and 12 results, information not available anywhere in the schema. It doesn't explain what the matches contain (similarity scores? screen metadata?) or pagination/result 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?

Two tight sentences, front-loaded with the purpose, followed by the workflow hint and the plan constraint. No filler; every clause adds actionable information.

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

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

No output schema exists, and the description never characterizes what comes back beyond 'matches', leaving the agent to discover result shape on the first call. The plan limits and base64 format are covered, but the interaction between the `limit` parameter and the free-plan ceiling is unexplained.

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 does clarify the critical format for `images` (base64, e.g. a UI screenshot), but the `limit` parameter is never mentioned — its relationship to the stated free-plan cap of 12 results vs. the schema default of 24 and max of 120 is left 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?

States a specific verb and resource: find catalog screens that visually resemble supplied images. The 'by image' qualifier implicitly separates it from text-based search_screens, but it never names that sibling or similar_screens, so the agent must infer the distinction.

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

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

Gives clear usage context and an explicit follow-up step ('then call get_screen on the matches to compare'), which is genuinely useful chaining guidance. It lacks any when-not guidance, e.g. when to prefer search_screens or similar_screens 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?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds the useful behavioral detail that results are ordered by the app's own flow themes, but says nothing about result count, cutoff thresholds, or what happens when no similar apps exist.

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 filler, and the core behavior (ranked by flow themes) is front-loaded. The second sentence is compact but contributes the schema-mismatched slug claim, so it doesn't fully earn 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 simple one-parameter read-only lookup this is close to adequate, and annotations cover safety. Gaps remain: no statement of typical result volume or ordering guarantees beyond the theme ranking, no handling of an unknown appId, and the slug ambiguity left unresolved.

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% for the single appId parameter, so the description must carry the burden — but its claim "Accepts an appId or slug" conflicts with a schema that defines only a required appId string with no slug field, leaving the agent unsure whether the slug is passed inside appId. It adds some meaning (the identifier scopes to one app) but introduces ambiguity rather than resolving it.

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

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

"Apps like this one, ranked from the app's own flow themes" gives a specific resource (similar apps) plus the basis of similarity (flow themes), so an agent knows what comes back. It does not distinguish itself from siblings like similar_screens or search_apps, which could cause a selection mistake in a crowded namespace.

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: nothing says when to prefer this over search_apps (keyword-based) or similar_screens. The only usage note is the input form, "Accepts an appId or slug," which is an input detail rather than a selection rule.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them: it discloses that results are visually matched rather than keyword-matched, that there is no quota, and that includeImages caps image returns at 4.

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

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

Three short clauses, front-loaded with what the tool returns, then the retrieval mode, then the one parameter worth explaining. The telegraphic style is dense but readable; nothing is wasted, though it is clipped enough that some intent must be inferred.

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?

Annotations cover the safety profile and there is no output schema to explain, so the remaining burden is modest. Still, for a 3-parameter tool with zero schema documentation, leaving screenDocId and limit undefined and the limit-vs-image-cap relationship unclear leaves the definition short of complete.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only explains includeImages ('returns the top matches as images (max 4)'). screenDocId and limit are never described, and the interaction between limit (default 12, max 48) and the 4-image cap is left 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 the resource (screens) and the retrieval criterion (visual similarity to a given screen), which is enough for an agent to know what it returns. It distinguishes itself from keyword search with 'Visual, not keyword', but never distinguishes itself from the sibling search_screens_by_image, which sounds like it covers adjacent ground.

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?

'Visual, not keyword' implies the usage context and 'no quota' hints the tool is safe to call liberally, but there is no explicit when-to-use or when-to-prefer-an-alternative statement. With a sibling named search_screens_by_image, the absence of 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.