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

With no annotations present, the description carries the full behavioral burden and does so in detail: refusal semantics (ok:false + reason, never substitute another field), channel isolation when scope=web/wechat and the requirement of a customer-supplied X-LLM-Key with the cost borne by the caller, the degraded-capability warning tied to interpreted.intent_source=llm vs rules_fallback, and the replay non-determinism caveat. It also discloses a subtle correctness trap — value is the verbatim source value while readable is the safe-to-quote conversion — and forbids derived quantities not present in the source.

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 purpose statement is front-loaded and correct, but the body is roughly 700 words for a 3-parameter tool, dense with ⭐/⚠️/⛔ markers increasing emphasis without increasing information. Several points are re-stated (refusal behavior appears twice, the readable-conversion rule is repeated) and a large block re-documents the return structure. Most sentences do carry real guidance, so this is bloat rather than filler, but it is well past the size the task warrants.

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 a natural-language-to-query tool with a large result envelope, the description covers what an agent actually needs to act correctly: domain coverage, refusal behavior, per-row quality thresholds (rerank_score ≥1.5 = good), and how to quote values safely. Because an output schema exists, the long walkthrough of data[]/citations[]/verification[] is largely redundant and displaces information the description genuinely lacks, such as the undocumented recency format. The result is complete on policy but over-explained on returns.

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 would be 3, but the description spends several paragraphs on `scope` and `replay=true` as though they were call arguments, and neither exists in the input schema. That is actively misleading: an agent following the text will pass scope=web or replay=true and be rejected, while the real parameters (recency, max_results) get no explanation beyond their schema strings. The valuable semantic content it does add (max_results caps evidence rows, q accepts full sentences) is already in the schema.

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 opening line names a specific transformation: natural-language question → our own data endpoint, returning a structured row plus evidence fields (value_hash / source_endpoint / params / as_of). It explicitly separates itself from ashare_evidence (keyword search over announcements/news/research) which is a genuinely useful sibling distinction. What it does not do is distinguish itself from the many structured siblings that answer the same questions directly (ashare_fund_flow, ashare_quote, ashare_lhb, ashare_news), so an agent still cannot tell when the NL wrapper beats a typed endpoint.

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 concrete, actionable routing rule: "问'多少/怎么样/是什么'用这个；问'发了什么公告/有什么新闻'用 evidence" — a real when-to-use vs. when-to-use-other statement. It also enumerates supported domains and, unusually, an explicit not-supported list (sectors, market stats, technicals, fundamentals, attribution, prediction) with the promise of ok:false refusal rather than substituting fields. The gap is that it never tells the agent when to prefer a specific typed sibling over this wrapper, and the routing rule only covers one of ~70 siblings.

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