send_single_message

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that recipient arrays are merged and deduplicated, that the call is a single batch operation, and that duplicate name matches cause the entire batch to fail. This goes beyond the bare operation and gives critical operational insight, though it omits details like return responses or error handling.

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 three sentences and front-loaded with the core purpose, followed by recipient behavior and a concrete prerequisite. Every sentence carries essential information; there is no filler or repetition of schema enum values.

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 the tool has 22 parameters, no output schema, and no annotations, the description covers the most critical operational context: batch semantics, deduplication, max recipients, name-match failure mode, and the upload_media prerequisite. It lacks explicit return value or error code information, but for such a many-parameter tool it is remarkably complete and actionable.

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 is 3, but the description adds meaningful cross-parameter semantics: it explains the relationship between userIds and userName (merged, deduplicated, max 20), states that media types require a mediaId from upload_media, and clarifies that userName matches must be exact. This adds value beyond the individual schema field descriptions.

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 sends a message to DingTalk users, enumerates supported message types, and specifies recipient resolution via userIds and userName. It distinguishes itself from the sibling send_group_message by focusing on user-targeted (not group) messaging and details the max 20 recipient batch behavior.

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 description gives explicit guidance on when to use upload_media first for media types, and heavily documents recipient constraints (max 20, exact name search, duplicate handling). It does not explicitly contrast with send_group_message, but the tool name and description imply direct-user versus group context, making the usage intent clear.

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