pty_send

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

With no annotations available, the description carries the full burden of behavioral disclosure, and it does so thoroughly: it explains send-only semantics, dispatch behavior with event_cursor receipt, fire-and-forget semantics, exit codes (0/3/4), no polling needed, foreground non-blocking execution, and the force:true caveat. This is far beyond what schema or annotations could convey.

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 a dense single paragraph rather than a structured output, which hurts scannability. However, nearly every clause carries actionable information — alternatives, exit codes, constraints — so the length is earned. It starts with the core purpose and then layers on detail, but a bulleted structure would improve readability.

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?

The description covers the full calling context: normal PTY vs agent dispatch, output retrieval, completion semantics, exit codes, sibling routing, and caveats like foreground execution and force mode. Since an output schema exists, return values don't need to be explained in prose. Nothing critical is missing for an agent to invoke this tool correctly.

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?

The schema already covers 86% of parameters, so the baseline is 3. The description adds cross-parameter context that the schema does not: the mark+enter interplay for completion detection, force:true being restricted to non-Claude agent sessions and incompatible with active turns, and the relationship between receipt fields and process API usage. These are meaningful semantics beyond 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 description opens with a clear statement of what the tool does: sends text to a session. It also explicitly differentiates itself from siblings by stating that output must be retrieved via pty_read, and that agent-session sends become automated dispatch, distinguishing it from pty_key, claude_turn, and claude_approval.

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 concrete routing guidance: use pty_read for result collection, use claude_turn for durable turns, use claude_approval for the approval UI, and do not use wait_command across process boundaries. It also clarifies when force:true is appropriate, which tells the agent exactly when this tool is or isn't the right choice.

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