Mobbin

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

Annotations already indicate a read-only, non-destructive operation, and the description adds substantial behavioral detail beyond that: results include inline low-res previews and per-screen previews, image_url is the high-res source, URLs expire after 30 days, and MCP Apps hosts render an interactive gallery. It also instructs the agent to examine images rather than rely on metadata.

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

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

The description is long but every section earns its place: purpose, image handling, expiry, citing, gallery behavior, and per-parameter guidance. It is not maximally concise, but it is well-organized and front-loads the core purpose before operational details.

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

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

For an 8-parameter tool with an output schema and read-only annotations, the description covers return characteristics, image fidelity, URL expiry, output destinations, and query quality. Nothing the agent needs to decide when to call or how to handle results is missing.

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

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

Schema coverage is 100%, but the description adds meaning well beyond the schema. The query parameter gets detailed examples and explicit anti-patterns; output_destination gets a full decision procedure with examples; output_tool and task_intent get consistency requirements. This materially improves 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 opens with 'Search Mobbin for multi-step user flows' — a specific verb, resource, and scope. This distinguishes it from the sibling tools search_screens and search_sections by focusing on multi-step flows with examples like onboarding and checkout.

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: natural language queries describing one journey, with strong do's and don'ts in the query parameter (avoid combining flows, negations, vague keywords) and guidance to name a specific app. It does not explicitly name sibling tools as alternatives, but the 'multi-step flows' framing and query guidance make the intended use clear.

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

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

Annotations already cover the read-only/safe profile, and the description adds substantial operational traits beyond them: inline images are low-res previews while image_url is high-res, URLs expire after 30 days, ai_usage_notice must be reproduced verbatim, and an interactive gallery renders on MCP Apps hosts.

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?

Purpose is front-loaded, but the body is dense with presentation/download instructions that occasionally restate the same point (expiration and download-vs-link appear twice). Most sentences earn their place, but it is longer than strictly necessary.

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 an output schema covering return values and annotations covering safety, the description still supplies the missing operational layer: image handling, citation format, and notice reproduction. Nothing an agent needs to call and present results correctly is absent.

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 itself fully documents all nine parameters (mode, limit, query, platform, output_tool, output_destination, etc.). The description adds little parameter-specific meaning, 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 ('Search Mobbin for UI screens using natural language') and describes the return ('matching screens with inline images and metadata'). It clearly differs from search_flows/search_sections by resource type, though it never names those siblings to sharpen 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?

Offers rich guidance: how to phrase queries (avoid negations, multi-screen intents, vague style words), when to download from image_url vs link mobbin_url, and when to display ai_usage_notice. It stops short of explicit tool-selection guidance against search_flows/search_sections.

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

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

The description goes far beyond the annotations (readOnlyHint, destructiveHint) by disclosing critical behaviors: inline images are low-res previews for the agent, image_url is the high-res version to use for saving/exporting, URLs expire after 30 days so files must be downloaded, and the recommendation to link to mobbin_url when citing. It also mentions the interactive gallery on MCP Apps. This is rich behavioral context 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?

The description is relatively long but every sentence earns its place, covering purpose, result interpretation, image handling, expiration, and output behavior. It is front-loaded with the core purpose and then addresses important operational details. No filler or redundancy, though it could be trimmed slightly without losing 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?

Given the tool's moderate complexity, the presence of an output schema, and rich annotations, the description is highly complete. It tells the agent exactly how to interpret results, when to download from image_url, how to cite, and what to expect regarding image previews and gallery rendering. No critical information for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail (including query formulation, output_destination choices, etc.). The tool description adds no new parameter-level semantics; it focuses on result handling and usage behavior. Since the schema carries the burden, 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 clearly states the tool searches for website sections via natural language, with examples ('About, Pricing, Footer'). It distinguishes from sibling tools by its specific resource type (sections vs flows/screens) and explicitly mentions returning section images. The purpose is unambiguous and actionable.

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 context on what the tool is for and includes query-construction guidance (e.g., avoid combining sections, search separately). However, it does not explicitly contrast with sibling tools like search_flows or search_screens, leaving the selection decision to inference from the name and purpose. No exclusions are stated, but the context is clear enough for most agents.

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