send_file

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

With no annotations, the description carries the full burden and does disclose real behavior: directory-scoped access control, refusal on misconfiguration, failure return when the outcome cannot be confirmed, and an explicit no-auto-retry policy. It does not explain the confirm/dry_run switches, which materially change what the call actually does (dry_run presumably prevents the send).

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?

Three sentences, each earning its place: purpose first, then preconditions, then failure/retry semantics. No filler and the most important constraint (send scope) is front-loaded.

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-value detail is not required, and the description covers the critical constraints plus failure semantics. The remaining gap is the semantics of confirm/dry_run and what counts as an 'explicit' recipient match, which an agent would otherwise have to guess.

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 0%, so the description must compensate for all four parameters. It clarifies recipient ('explicitly specified' contact or group) and the file_path constraints (must exist, must be in an allowed directory), but confirm and dry_run receive no explanation at all, leaving half the parameters opaque.

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 states a specific verb and resource: send a local file to an explicitly named contact or group chat. The word 'file' (文件) plus the required file_path/recipient pairing distinguishes it from the sibling send_message, which handles text messages, without needing the schema. No ambiguity about what the tool does.

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?

Preconditions are stated explicitly: the file must exist, must live inside an allowed directory, and sending is refused when no sendable directory is configured. What is missing is routing guidance against alternatives (e.g., when to prefer send_message vs send_file, or behavior for ambiguous recipient names).

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