terminal_start

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

Annotations only declare the safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds real behavioral context beyond that: the call returns immediately with a session ID rather than blocking, commands must be pre-approved with no argv/shell substitution, and cwd is confined to approved roots. It does not disclose lifecycle obligations (sessions persist until terminated) or what timeout_ms governs.

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 core behavior is front-loaded in the first sentence, and the constraint sentences are terse and non-redundant. The profile list is a dense run-on line whose purpose is unclear in context, slightly blunting the structure.

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 values are covered, and the safety posture is annotated. But for a session-creating tool with four undocumented parameters, the description leaves gaps: what timeout_ms applies to (start vs. process lifetime), what env is merged into, and whether the started session must later be terminated to avoid leaking resources.

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% for all four parameters, so the description must carry the load. It only clarifies cwd ('must remain under approved roots') and gestures at command_id via the 'Default profiles' list without ever saying those are valid command_id values. env and timeout_ms receive no explanation at all.

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 specific verb and resource ('Start a real approved process') plus the immediate outcome ('return its persistent session ID'), which is enough to distinguish it from terminal_write/read/status/terminate. It does not explicitly name those siblings, but the session-ID framing makes the start-then-attach relationship clear.

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 'approved process' framing and the constraint list ('No client argv or shell substitution is accepted') imply you must already have an approved command_id and then use terminal_write/read to interact, but the description never states the sequencing or when-not-to-use explicitly. Usage is inferable rather than spelled out.

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