ShipSwift

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

While annotations declare the operation is read-only and safe, the description adds valuable behavioral context about the response payload: copy-paste-ready Swift code, architectural explanations, and potential backend modules (Hono/Node.js/AWS CDK). This compensates for the missing output schema by describing return contents.

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 constructed sentences. The first establishes the retrieval operation, the second details the return payload. Every word serves a purpose; no tautology or redundant qualification.

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 lack of output schema, the description appropriately explains return values (code content, architecture docs). Annotations cover safety properties. Minor gap: could explicitly address the relationship to sibling discovery tools, but the domain concept (recipe) is well-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?

With 100% schema description coverage for the single 'id' parameter, the schema already documents the expected format with examples. The description relies appropriately on the schema without redundant repetition, meeting the baseline for high-coverage schemas.

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 action (Get), resource (recipe), and lookup method (by ID), distinguishing it from siblings listRecipes and searchRecipes. The second sentence further clarifies what a 'recipe' entails (Swift source code, architecture explanations), grounding the abstract resource in concrete terms.

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 'by ID' implies use when a specific identifier is known, contrasting with siblings that suggest listing or searching. However, it lacks explicit guidance such as 'Use searchRecipes if you don't know the ID' or sequencing recommendations between discovery and retrieval 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?

Annotations establish the safety profile (readOnly, idempotent), while the description adds essential behavioral context: it defines what a 'recipe' actually contains (copy-paste-ready implementations), discloses the technology coverage scope (iOS native through AWS backend), and clarifies the categorical organization available for filtering.

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 information-dense sentences with zero waste: first establishes purpose and content nature, second defines technology scope, third details category mappings. Uses em-dash effectively for parenthetical clarification. Front-loaded with critical distinctions.

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 simple 1-parameter schema with complete coverage and explicit safety annotations, the description compensates well for the missing output schema by thoroughly documenting the domain model (recipe content types, technologies, categories). A perfect score would require pagination hints or return structure details.

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?

With 100% schema coverage, the baseline is 3. The description elevates this by adding semantic meaning to the category parameter's enum values—explicitly mapping 'animation,' 'chart,' 'component,' and 'module' to concrete content examples (e.g., 'full-stack modules including auth, camera, subscriptions'), which aids agent selection.

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 the specific verb 'List' and resource 'production-ready SwiftUI code recipes,' clearly defining the tool's function. It distinguishes the content type from tutorials using 'not a tutorial,' and implies differentiation from siblings (list vs. get/search) through its plural resource naming.

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?

While the description provides clear context about available categories and content types, it lacks explicit guidance on when to use listRecipes versus getRecipe (single retrieval) or searchRecipes (filtered querying). Usage must be inferred from the naming convention and category parameter.

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 confirm read-only/idempotent safety. The description adds valuable behavioral context: it searches across four specific fields (titles, descriptions, tags, full source code) and clarifies the domain (iOS/SwiftUI/backend recipes), which annotations do not cover.

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, zero waste. Front-loaded with the core action ('Search recipes'), followed by scope details and usage examples. 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?

For a single-parameter search tool with simple schema, good annotations, and no output schema, the description is complete. It covers search scope, domain applicability, and provides concrete examples without needing to describe return values.

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

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

With 100% schema coverage, baseline is 3. The description adds semantic value by contextualizing the query parameter for specific domains (iOS, SwiftUI, backend) and expanding examples beyond the schema (subscription, paywall, infrastructure vs. schema's shimmer, authentication, chart).

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

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

The description uses a specific verb ('Search') with clear resource ('recipes') and scope ('across titles, descriptions, tags, and full source code'). It distinguishes from sibling tools getRecipe and listRecipes by emphasizing keyword-based search over ID retrieval or enumeration.

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?

Provides explicit usage context ('Use for any iOS, SwiftUI, or backend topic') and rich examples (subscription, authentication, camera, etc.). Lacks explicit contrast with siblings (e.g., when to use listRecipes instead), but the search mechanism description implies differentiation.

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