House AI

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

Annotations already declare non-read-only, open-world, non-idempotent behavior, so the bar is lower. The description still adds real value by disclosing the credit cost ('Uses one House AI design credit'), which the agent needs for cost-aware decisions; it does not say whether the source photo is preserved or output is returned as a new asset.

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 core action, followed by concrete examples and the cost note. No wasted words.

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 generative mutation tool with no output schema and fully documented params, the definition covers purpose, examples, and the credit cost. It omits what the result looks like and whether a failed generation consumes a credit – a modest gap.

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 photo, photo_url, floor_style, and photo_upload_id. The description's style examples overlap with the floor_style schema example ('white oak herringbone'), leaving baseline 3 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?

States a specific verb and resource ('Replace the floor in a room photo with new flooring') and frames the goal (preview a renovation). It does not name or contrast with close siblings like paint_walls or redesign_room, so it falls short of full sibling differentiation.

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 'to preview a renovation' implies the use case, and flooring-style examples suggest when the tool fits, but there is no explicit when-not guidance or pointer to alternatives such as redesign_room for broader changes. Usage is inferable rather than stated.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false), so the added value here is the credit-consumption warning ('Uses one House AI design credit'), which is real cost-awareness context an agent needs before calling. It does not clarify whether the source photo is preserved or what is returned.

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 sentence, front-loaded with the action and outcome, then use cases, then the credit cost. 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 no-output-schema tool with a nested photo object fully documented in the schema, the description covers purpose, use cases, and cost. Only the return behavior (e.g., a generated image reference) is left implicit, which is 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 description coverage is 100%, and the schema itself explains photo, photo_url, and photo_upload_id including the get_photo_upload_link dependency. The description adds no parameter guidance beyond that, so baseline 3 applies.

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

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

States a specific verb and resource: 'Remove the furniture and clutter from a room photo to see the empty space.' This clearly separates it from furnish_empty_room and redesign_room by outcome, though it never names a 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?

Gives concrete when-to-use contexts (decluttering, moving, planning a new layout) and flags the credit cost before invocation. It stops short of stating when NOT to use it or pointing to furnish_empty_room as the inverse operation.

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, openWorld and non-destructive, so safety is covered. The description adds useful context beyond them by naming the return payload ('products with prices, sellers and links'), which matters because there is no output schema; it stops short of noting result variability or that availability depends on country.

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, no filler: the capability and examples come first, the return shape second. Every clause ('real furniture', 'optionally under a budget') carries information an agent can act on.

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 annotations covering the safety profile and the schema fully described, the remaining burden is the return shape, which the description addresses. It is slightly incomplete in not mentioning result variability, empty results, or how country affects pricing, but the definition is sufficient to call 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?

Schema description coverage is 100%, so all four parameters are already documented including examples and the two-letter country code format. The description only reiterates the optional budget concept, adding no syntax or behavioral detail beyond the schema; 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 House AI's shop for real furniture and home decor') and enumerates concrete product categories, so an agent knows exactly what this retrieves. It does not, however, contrast itself with adjacent siblings such as shop_this_look or furnish_empty_room, which also surface purchasable products, leaving the boundary implicit.

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 phrasing 'real furniture ... you can buy' implies this is the shopping path rather than the design/rendering tools, and 'optionally under a budget' hints at the budget parameter. But there is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the routing 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 declare readOnly=false, destructive=false, openWorld=true and non-idempotent, so the safety profile is covered. The description adds a genuinely non-structured behavioral fact: each invocation "Uses one House AI design credit," which is exactly the kind of cost signal an agent should weigh before calling. It stops short of covering async/latency or what a failed or low-credit run yields.

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, front-loaded with the core definition, followed by the cost note. No waste, though "for a new home, a rental or a listing" is the softest part and could be tightened without loss.

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 and a nested photo object, the description plus the rich schema descriptions together are sufficient to call it correctly. The remaining gap is what comes back — a staged image, presumably listed under list_my_designs — and whether credits are consumed on failure, neither of which is stated.

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

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

Schema description coverage is 100% and the schema itself distinguishes the three mutually exclusive photo inputs (attached photo, photo_url, photo_upload_id) with clear per-field notes. The description only echoes "from a photo in a chosen style" and adds nothing about which photo channel to prefer, so the 100%-coverage baseline of 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?

"Virtual staging: furnish and decorate an empty or bare room from a photo in a chosen style" gives a specific verb pair, the resource (a room photo) and the required input dimension (style). The word "empty" implicitly separates it from a redesign of an already-furnished room, though no sibling is named.

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

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

"for a new home, a rental or a listing" gives audience context and "empty or bare room" scopes the input, which is a usable condition for selection. But there is no explicit exclusion or routing — it never says to use redesign_room when the room already has furniture, or empty_room when the goal is removal, so the agent must infer 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds the useful behavioral fact that the result is a rich descriptive profile rather than a list or an action. It doesn't say what happens when the style doesn't exist or that the 'space' argument selects a different catalog (exterior/landscaping).

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, front-loaded with the resource and payload, followed by concrete usage triggers. No filler and nothing repeated.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the returned fields, which is the key omission filled. It is short of complete because the non-interior catalogs (exterior, landscaping) and unknown-style behavior go unmentioned.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the enum for 'space' and an example value for 'style'. The description's example ('what is Japandi?') restates what the schema already shows, adding no new parameter semantics, 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?

"Details for one House AI design style" names the resource and enumerates the specific payload (color palette, materials, furniture, textiles, lighting, decor, avoid-list), so the agent knows exactly what comes back. The verb is implicit rather than stated, and the closest sibling (search_design_styles) is never named, so differentiation must be inferred from "one".

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?

Two concrete use cases are given: explaining a style and planning a room makeover before redesigning, which also ties it to the redesign_room sibling. What's missing is the counterpart guidance – that style names should be discovered via search_design_styles, or what to do when the style name is unknown.

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 safety and repeatability are covered elsewhere. The description adds that the link spans two platforms and what happens to the user's designs in the app, but says nothing about link lifetime, whether it is personalized, or whether it can be shared — the details that would actually change how an agent presents it.

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 sentence that front-loads the deliverable (the download link) and then adds the value context. No filler, no repetition of the title or annotations.

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 zero-parameter, no-output-schema read, the description tells the agent enough to call it and to explain the result to a user. The only gap is that it doesn't clarify whether the returned link is a generic store URL or something tied to the user's account, which would matter for how the agent frames it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. The description correctly does not waste words on inputs.

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 concrete artifact returned (a download link for the House AI app) and scopes it to iPhone and Android, so an agent knows exactly what this produces. It doesn't explicitly contrast with siblings, but the resource is distinctive enough that confusion with actions like redesign_room or list_my_designs is unlikely.

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: the mention of saved designs, continued room editing, shopping the look and trying styles suggests calling this when the user wants to move to the mobile app. There is no explicit when-to-use or when-not-to-use guidance, and no sibling tool is named as an alternative.

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 this a safe, read-only, idempotent, closed-world operation. The description adds useful behavioral context by clarifying that credits apply to today or the current plan period, resolving a key ambiguity about the returned quantity.

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 sentence that is front-loaded and free of waste. Every word contributes to defining the returned quantity.

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 zero parameters, complete annotation coverage, and no output schema, the description provides enough context to call the tool. It could clarify the exact return shape, but that is a minor gap.

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 takes zero parameters, so there are no parameter semantics to document. Baseline for zero-parameter tools is a 4.

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 that this tool reports the remaining House AI design credits, a specific resource and quantity. It does not explicitly distinguish itself from sibling tools, though the credit-related purpose is distinct from design-action siblings.

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

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

Usage is implied by the name and description: check remaining design capacity. There is no explicit guidance on when to call it versus alternatives, nor any exclusion 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?

Annotations already declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful workflow context: it creates a private link and the resulting upload_id must be passed to the redesign tool, though it omits link expiry or authentication 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?

Three short sentences, front-loaded with the action and followed by the use condition and next step. No sentence is redundant or restates structured fields unnecessarily.

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 zero-parameter tool with no output schema, the description covers purpose, when to use it, and the key return/handoff value upload_id. It could say more about link lifetime or exact return shape, but it is largely complete 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?

There are zero input parameters, so the schema covers all input semantics and the baseline is 4. The description appropriately introduces no parameters and instead explains the upload_id handoff value that the agent must use afterward.

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: make a private link for uploading room, house, or yard photos. It also frames the tool's role in the workflow, making it distinguishable from redesign and furnishing siblings.

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

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

Gives an explicit trigger: use when the user wants a redesign, has not attached a photo, and the app cannot pass attached photos to tools. It also describes the follow-up handoff of upload_id, though it does not name the specific redesign sibling such as redesign_room or redesign_exterior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: results are newest first and include image links, and it enumerates the kinds of designs returned.

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 efficient sentence that front-loads the core resource and immediately adds ordering and return-content details. There is no redundant or 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 read-only list tool with one optional parameter and no output schema, the description gives enough context about what is returned, including categories, ordering, and image links. It could optionally mention default result count or pagination behavior, but the schema covers the limit mechanics.

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

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

Schema description coverage is 100%, and the single limit parameter is already documented with default, minimum, and maximum values. The description does not add any parameter-specific detail beyond what the schema provides, so the 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 that this returns the user's recent House AI designs, including room redesigns, exteriors, and paint/flooring previews, with newest-first ordering and image links. It is specific about the resource and return contents, though it does not explicitly contrast this retrieval tool with sibling creation tools like redesign_room or paint_walls.

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 provides no explicit when-to-use guidance, prerequisites, or alternatives. Usage is only implied by the tool name and the fact that it lists designs rather than creating them.

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 declare a non-read-only, open-world, non-idempotent operation, and the description adds the crucial cost disclosure: 'Uses one House AI design credit.' That is real information not present in the structured fields. It does not say what the result is (rendered image vs. saved design) or whether it appears in list_my_designs, so it stops short of 5.

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 tightly packed sentence that front-loads the action, the input, the outcome, and the cost. No filler or repetition.

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 6-parameter, nested-object generation tool with full schema coverage and annotations, the description covers purpose and cost well. The remaining gap is the return behavior — whether an image or a saved design comes back — which matters for a credit-consuming generation tool with no output schema.

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 per-field descriptions for color, photo, space, photo_url, room_type, and photo_upload_id, so the schema already carries parameter meaning. The description only reinforces the color phrasing ('sage green', 'warm white with black trim'), which is marginal added value over the schema's own example.

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 concrete verb and resource ('repaint the walls in a photo of a room or house with a new paint color') plus the intent ('preview a color before painting'). An agent can tell this is a targeted recolor rather than a full redesign, though it never names how it differs from siblings like redesign_room or redesign_exterior.

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 'to preview a color before painting' implies the use case (try a color on an existing photo rather than restyle the room), and example colors show expected phrasing. However, there is no explicit when-to-use/when-not guidance and no named alternative such as redesign_room for broader changes, leaving the routing to inference.

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 is a non-read-only, open-world, non-idempotent but non-destructive operation. The description adds the crucial cost disclosure ('Uses one House AI design credit') and the return artifact ('photorealistic image'), which the annotations do not cover. Credit consumption is the standout value-add.

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 that front-load the purpose, then the return value and cost. No filler or repetition of schema fields 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?

For an 8-parameter tool with a nested photo object and no output schema, the description covers purpose, output format, and cost. The photo-vs-photo_url-vs-photo_upload_id selection logic is left entirely to schema descriptions, which is acceptable given full coverage but is the one gap.

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 every parameter carries its own description, so the schema does the heavy lifting. The description only gestures at the field set (siding, paint, trim, roof color, front door) without adding syntax or guidance beyond the schema's examples.

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 ('AI exterior design and landscaping'), enumerates the surfaces it touches (siding, paint, trim, roof color, front door, yard, patio, garden), and implicitly distinguishes itself from redesign_room by scoping to the outside. An agent can tell what it produces (a photorealistic image) 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?

Gives clear conditions for use ('from a photo', exterior vs yard) and the schema's focus enum reinforces the two modes. It does not explicitly name alternatives such as redesign_room or when to prefer one, so routing is implied rather than spelled out.

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

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

Beyond the annotations (non-read-only, open-world, non-idempotent, non-destructive), the description discloses the two facts an agent most needs: the call consumes one House AI design credit, and the output is a photorealistic image preserving the room's layout. It also flags that a photo is mandatory, which is the main failure mode.

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

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

The core action and its output are front-loaded in the first two sentences, with examples woven in rather than listed separately. The cost and photo-requirement facts come last as scannable constraints; nothing is redundant with the title or schema.

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 a nested photo object and no output schema, the description covers what is generated, what is preserved, what it costs, and how to supply the image. Remaining gaps are minor: no mention of how renovation=true interacts with the credit cost or what happens if the generation fails.

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 baseline is 3, but the description adds real value by explaining that the three photo-related parameters are alternative input routes (attached photo vs public link vs upload_id from get_photo_upload_link), a relationship the schema does not state. It also illustrates the style parameter with several concrete style names.

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?

Opens with a specific verb set (redesign, redecorate, remodel) applied to a concrete resource (a room from a photo) and names the style dimension with concrete examples like 'Japandi living room' and 'modern farmhouse kitchen'. It also states an output ('a photorealistic image of the new design') and a constraint ('keeps the room's layout'), which separates it from paint_walls or change_flooring in spirit, though it never names the sibling tools explicitly.

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

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

Gives clear preconditions: a photo is required, and it enumerates the three acceptable sources (chat attachment, public link, upload_id from get_photo_upload_link), routing the agent to a specific sibling for one path. It stops short of stating when to prefer empty_room, furnish_empty_room, or paint_walls instead, so the exclusion side is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by saying it 'Returns style names with a short description' and that a returned name can be passed to the redesign tools. It does not describe result limits, pagination, or empty-result behavior, so it stops short of full transparency.

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-loaded: it opens with the catalog scope, then gives usage conditions, then explains the return shape and next step. Every sentence serves a distinct purpose with no wasted phrasing.

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 browse tool, the definition is complete enough: annotations cover safety, the schema fully documents both parameters, and the description explains what is returned and how to use the result. No output schema is necessary because the description already says it returns style names with short descriptions.

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%, including enum values and an example query, so the schema already defines both parameters well. The description mentions the style catalog broadly but does not explain how the 'query' and 'space' parameters interact or add syntax beyond what the schema provides. A baseline 3 is appropriate when the schema carries parameter semantics.

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

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

The description states a specific verb and resource ('Browse House AI's interior design, exterior and landscaping styles') and gives concrete examples (Japandi, coastal, farmhouse). It clearly separates this catalog-browsing tool from the redesign tools by saying to 'pass a name to the redesign tools,' but it does not explicitly distinguish itself from the sibling get_design_style 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?

It provides clear usage context: 'Use it when someone is deciding how to redecorate, remodel or restyle a room, a house front or a yard, or wants style ideas.' It also gives a follow-on action ('pass a name to the redesign tools'), but it does not state when an agent should use get_design_style instead of this browse tool.

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=true, destructive=false, idempotent=true and openWorld=true, so the safety profile is covered and the bar is lower. The description adds only that the result set is real purchasable products, leaving unstated which photo input wins when several are supplied and what the results contain (retailers, prices, availability).

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 with the purpose front-loaded and the example immediately after. The second sentence is where the wasted/incorrect instruction lives, but overall there is little padding.

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, so the description should say what comes back from a shopping search; instead it only says real products are found. For a 5-parameter tool with a nested photo object and three alternative photo sources, the description should do more than restate the happy path.

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 baseline is 3 and each parameter including photo.download_url and photo_upload_id is documented in the schema. The description adds nothing about the mutual exclusivity of photo / photo_url / photo_upload_id, and its instruction to 'pass the design's image_url' names a field that does not exist in the schema, which mildly undercuts the schema it should be reinforcing.

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?

A specific verb+resource: 'find real products that match an item' in a room photo or design, with concrete examples (sofa, rug, pendant light). It is distinguishable from redesign_room and find_furniture_and_decor in spirit, but never names those siblings explicitly to draw the boundary.

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 an originating context (an item in a room photo or House AI design) and an example, which implies when to call it. But there is no explicit when-not, no prerequisite ordering (e.g. get_photo_upload_link before passing photo_upload_id), and no comparison against find_furniture_and_decor or the redesign tools.

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