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 non-obvious domain context: that price and stock quantity are deliberately absent and only brand/name/spec are exposed, which prevents an agent from promising unavailable data.

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, scope and alternatives are front-loaded in the first two sentences; the 20-item category list is verbose but earns its place since the schema has no enum. Only minor trimming would be possible without losing signal.

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, four-parameter search tool with no output schema, the description covers scope, the returned field set, category vocabulary and the fallback route for purchase intents. It stops short of describing result ordering, pagination, or behavior when no match is found.

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 75%, with brand and query already documented. The description adds real value by enumerating the full allowed category vocabulary (마루/바닥재, 벽 마감, 몰딩 …), which the schema does not encode as an enum, materially improving category matching.

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 ('내만집 스토어에 등록된 인테리어 자재 상품을 카테고리·브랜드·키워드로 찾는다') and explicitly bounds what is returned (brand, product name, spec only; no price or stock). It also separates itself from the purchase-oriented sibling nmjib_material_request.

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 concrete trigger phrasings ('내만집에 어떤 강마루 있어?', '제일벽지 실크 벽지 목록') and explicitly routes price/purchase intents to nmjib_material_request or the web app. Both when-to-use and when-not-to-use are covered.

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