chat_send

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds genuinely useful side-effect detail: plain group sends are save-only while to/notify enqueue for delivery, ack_ids merges acks without mixing public and private targets, key provides idempotent retry, and speaking grants no execution permission. It omits rate limits and any failure/partial-delivery behavior.

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-loads the core action, then layers delivery-mode, ack, and idempotency rules in short clauses with no filler. The telegraphic phrasing ('reply_to+delivery_id 默认确认一条') is dense enough that a reader may need a second pass, which keeps it off a 5.

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?

With 10 parameters, no output schema, and only 30% schema coverage, the description does not say what the call returns – notably whether a message/delivery identifier comes back that reply_to and delivery_id later consume. It also leaves interaction between room, server and session_id (network room vs local room) undiscussed, so an agent must consult the schema to assemble a correct call.

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 only 30%, so the description must carry the load, and it does: it defines the meaning of to, key (idempotent retry), reply_to+delivery_id (ack a single message) and ack_ids (batch ack of already-processed messages, no cross-mixing of public/private or private targets). room and content remain obvious, and server/session_id/notify are covered by schema text, leaving only minor gaps.

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?

Opens with a concrete verb+resource ('以自己的昵称发言' – speak under your own nickname), so the agent knows this posts a message to a room. It also carves out scope against siblings by contrasting plain group broadcast (save-only) with private/reply/notify paths, but never names chat_receive or chat_ack explicitly, so differentiation requires inference.

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 conditional guidance for individual fields ('to 私聊', 'notify 才进入目标待收队列', 'reply_to+delivery_id 默认确认一条'), which implies when each mode applies. However it never states when to use this tool versus chat_ack for acknowledgement, nor any exclusions such as rooms you have not joined, so the when-to-use picture is only partially implied.

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