Focus a control

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is carried by structured data; the description does not contradict it. It adds genuine context beyond the annotations: focus may be refused for some controls, and the call reports what NVDA spoke afterward. It does not address why the operation is flagged destructive or what state changes a focus move can cause.

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?

Two short sentences, front-loaded with the action and its outcome, followed by the workflow hint and the failure caveat. Nothing is repeated from the schema or annotations and no sentence is wasted.

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 the description need not explain return values, and the stated 'report what NVDA said' is consistent with it. For a 6-parameter mutation tool it covers the prerequisite, the follow-on tool, and the main failure mode. Only a note on interaction with nvda_activate_object or on what the destructive hint implies 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 description coverage is 100%, so every parameter (id, record, settle_ms, timeout_ms, until_speech, record_within) is already documented, and the description adds only the notion that id originates from nvda_find_objects, which the schema already states. No added semantics such as how until_speech interacts with settle_ms are supplied. Baseline 3 is appropriate when 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 and resource ("Move keyboard focus to a control") and ties the target to nvda_find_objects, which is how the required id is obtained. It also names the forward chaining sibling (nvda_type_text), so an agent can place it in a workflow. It stops short of distinguishing itself from nvda_activate_object, the other sibling that acts on an object id.

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?

"Use this to reach an edit field before nvda_type_text" gives explicit when-to-use guidance and a clear ordering relative to another tool. The caveat "Some controls cannot take focus" warns of a failure mode. No explicit when-not-to-use or statement of which alternative to pick when focusing fails (e.g. nvda_activate_object), which keeps it from a 5.

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