request_access

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

With no annotations provided, the description carries the full burden. It does disclose the key interactive trait: 'The user will approve or deny access for each app,' signaling this is a user-facing authorization step. However, it stops short of describing what happens when access is denied, whether the call is blocking, or what the return value looks like, which an agent would need to handle the denial path.

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?

Three short sentences, each earning its place: purpose, ordering constraint, and the user-interaction expectation. The critical 'call FIRST' guidance is front-loaded immediately after the purpose statement. Zero filler or redundant restatement of the schema.

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?

For a single-parameter gatekeeper tool with no output schema, the description covers the essentials: what it does, when to call it, and the user approval/denial interaction. The main gap is the absence of post-condition behavior (what the tool returns on approval vs denial and how the agent should react to a denial), which is slightly more important here because this tool is a mandatory prerequisite for all siblings.

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%: the schema fully documents 'apps' as the list to request access for, including bundleId with an example and displayName. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies. No compensation needed, but none provided either.

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 states a specific verb and resource: 'Request permission to control specific applications.' This clearly distinguishes it from the sibling tools (type, click, scroll, etc.), which are all action tools that presuppose access; this tool is the permission-gating prerequisite. The phrase 'Call this FIRST' reinforces its distinct role.

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 explicit when-to-use guidance: 'Call this FIRST before any other computer-use tool.' This tells the agent the ordering constraint relative to the sibling set. However, it does not address the when-not-to-use case (e.g., if access was already granted) or name specific alternatives.

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