zas_receive_direct

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

With no annotations, the description carries the full burden and does so well: it discloses the one-minute call timeout, the ten-minute offer wait, the returned job id to poll via zas_jobs, the returned path, the no-overwrite guarantee, and that nothing is stored. It does not describe failure/timeout outcomes when no offer arrives, which is the main remaining gap.

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, then trigger, then constraints, then return/behavior — good ordering. The closing sentence about the owner seeing items "this agent sends" with the >_ mark concerns sends, not receives, so it is slightly off-topic for this tool.

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?

No output schema exists, and the description compensates by stating the return value (path written) and the async job-id pattern. Combined with timing and permission preconditions, an agent has nearly everything needed, missing only explicit error/no-offer handling and sibling disambiguation.

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 100% for both parameters (dest, channel), and the description adds only indirect hints ("writes the file to disk", "returns the path written") without new syntax or default semantics. Baseline 3 applies since the schema does the heavy lifting.

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 (receive a file the owner sends through Directo) and the effect (written to disk on this machine). It is distinguishable from zas_send_direct and zas_send_file, but never mentions zas_receive_direct_fallback, which is the closest alternative an agent would need to disambiguate from.

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?

"Call it when the owner says they are sending you something" gives a clear trigger, and preconditions are spelled out: Directo-mode channel only, grant must include reading. No exclusion or explicit fallback routing is provided, so the agent cannot tell when to prefer zas_receive_direct_fallback instead.

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