search_promotions

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

No annotations are provided, so the description carries the full burden. It discloses the underlying API endpoint (GET /v1/promotions/search) and the return structure (dict with total_found, returned, items[] and per-item fields). This gives the agent a clear picture of what will happen, though it doesn't detail edge cases like exact-match semantics or pagination behavior beyond the response counts.

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 highly structured with clear sections (用途, API, 回傳結構). It is concise, uses bullet-like formatting, and every sentence contributes meaningful information. No fluff or redundancy.

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 search tool with 2 parameters and no output schema, the description provides the essential information: purpose, API endpoint, and return fields. It even mentions the next step (get_promotion_detail) and includes pagination-related counts (total_found, returned). Lacks examples of actual requests or deeper pagination logic, but overall it is sufficiently complete.

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%: both keyword and max_results are described in the input schema. The description adds examples of keyword values and explains that results contain ids for further lookup, but it mostly reinforces what the schema already says. No substantial new parameter semantics are introduced.

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's function: searching promotions by keyword (依關鍵字搜尋促銷活動). It provides concrete examples (週年慶, 黑五) and distinguishes it from siblings by noting it returns ids for further use with get_promotion_detail, setting it apart from list_promotions and inspection tools.

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 '用途' section provides clear context: use this to quickly find promotions by specific name. It implies this is for targeted search rather than general listing, and points to get_promotion_detail for follow-up. It stops short of explicitly naming list_promotions as the alternative for full listings, but the context is sufficient.

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