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

Description adds significant behavioral detail beyond annotations: answers are strictly sourced from the shop's spec sheet and live stock, nothing is model-generated, fit data belongs to specific items, and questions that get refused are recorded for the owner. It explains the open-world nature (live reads) and the side effect of recording questions, aligning with openWorldHint=true and readOnlyHint=false without contradiction.

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

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

The description is extensive and somewhat verbose, but it is front-loaded with the core purpose and examples. Every sentence adds valuable context about data sourcing, fit interpretation, and refusal behavior. It could be tightened, but the length is justified by the tool's complexity and the absence of an output 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?

Given there is no output schema, the description must explain what the agent will receive. It details that answers consist of rows from the shop's spec sheet and live stock data, including ids, variants, preview images, descriptions, and per-item size charts where available. It also covers refusal behavior. This is sufficient for an agent to know what to expect when invoking the 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?

Schema coverage is 100% for both parameters, but the description enriches their meaning: 'shop' is identified as a slug, and 'question' is described as plain words with a recommendation to ask one subject per question. It also provides concrete examples that demonstrate the expected format and scope, going well beyond the schema's brief descriptions.

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 explicitly states the tool's purpose: asking a shop's brain a question in plain words and receiving answers from the shop's ratified spec sheet plus a live stock read. It gives concrete example questions and clarifies what is and isn't included, distinguishing it from sibling tools like concierge_document or market_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?

The description provides clear usage context: it is for asking natural-language questions about a shop's products, stock, and services. It does not explicitly name alternatives or state when not to use it, but the examples and emphasis on 'plain words' imply this is for conversational queries rather than structured lookups. No direct exclusions are given.

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