tailscale_get_oauth_app

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable non-obvious behavior: the client secret is not returned and only exists at creation time. This prevents the agent from assuming a getter returns all stored configuration. It also names the configuration fields returned, which is useful given there is no output schema.

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 sentences with no filler: the first states the operation and scope, the second gives the use case and the key behavioral caveat. Every sentence earns its place, and the most important identifying detail is front-loaded.

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 simple single-parameter read-only getter with rich annotations, the description is complete. It specifies what is returned, what is not returned, and when to use it. The lack of an output schema is compensated by naming the returned configuration fields and the secret caveat.

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%, and the appId parameter is already well described as 'The OAuth app ID returned by tailscale_create_oauth_app'. The description only rephrases this as 'by its app ID', adding no new semantic information. Baseline 3 is appropriate when the schema fully documents the parameter.

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 uses a specific verb 'Get' with a clear resource ('an OAuth App's configuration') and identifies the lookup key ('by its app ID'). It enumerates the fields returned (name, redirect URIs, scopes), making the tool's purpose unambiguous and distinguishable from getters for other resources like tailscale_get_key or tailscale_get_webhook.

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 an explicit use case: 'Use this to verify an app was registered as intended.' It also provides a practical caveat about the client secret being unavailable, which helps agents avoid expecting it. It does not explicitly name alternative tools for when this tool is not appropriate, but the contextual guidance is sufficient for a simple getter.

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