coolapk_suggest

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

No annotations are provided, so the description carries the burden. It discloses that input may be a spoken-style long sentence and that the output is Coolapk-suggested canonical search terms, but says nothing about whether suggestions come back as a list, whether auth/login is required (a sibling tool tracks login status), or about rate limits.

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?

Front-loaded with the action and return, followed by the use case. The Args block partially restates the earlier point about colloquial phrasing, but the total length is small and nothing is padded.

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?

An output schema exists, so return values need not be described. For a one-parameter read helper, the description covers purpose, input flexibility, and the downstream workflow; the only real gap is auth/severity context, which no annotation supplies.

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 0% — the schema only types 'keyword' as a string. The description compensates well by explaining that the keyword may be natural language or a half-formed phrase, including a conversational long sentence, which meaningfully relaxes what an agent would otherwise assume.

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+resource ('获取酷安搜索联想词') and adds a functional framing ('查询改写积木') that separates it from a results-returning search tool. It never names coolapk_search explicitly, so the sibling differentiation is implied rather than stated.

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 a clear use condition: when the request is colloquial or a half-formed keyword, rewrite it into Coolapk-style terms first, then search. It does not name the follow-up tool or state when this step should be skipped.

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