Acquire, renew or end an input interaction

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

Lease defaults/max are also in the schema, but the description adds the behavioral payload: bridge refuses all writes with [busy], reads stay available, renew moves the deadline without pressing, end releases keys newest-first/aborts the sequence/reports unresolved, and interactions are never resumed. Effectively complete disclosure-bearing text for an unannotated tool.

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?

Dense and front-loaded with the acquire-lifecycle model, then the deadline and end semantics. Nearly every clause carries information, though the single long paragraph is heavier than ideal for scanning.

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?

With no annotations or output schema, the description is still sufficient: lease, busy-blocking, prerequisites, and failure modes are all covered. Nothing an agent needs to acquire/renew/end correctly is missing.

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 75%, so the schema documents most parameters. The description adds the consequence of lease_ms expiry (keys released) and ties interaction to renew/end across calls, going beyond the schema's terse field notes.

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 specific verbs (acquire/renew/end) and resource (a leased input interaction) and explicitly names the sibling tools that consume the returned id (gma3_hardkey/gma3_keyboard, gma3_type, gma3_input_sequence). An agent can distinguish it from those siblings without opening schemas.

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?

Explains the exact coordination model: acquire when you need console key input across several calls, end as soon as the interaction is done, renew when you need more time. It also states prerequisites (input must be enabled) and the edge case (end works while input is disabled), leaving little to inference.

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