Enable the app portal

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the auth precondition, the exact error code other callers receive (access_request_owner_required), the non-destructive side effect model (grants and registrations stay intact, daemon hot-reloads independently), the funnel refusal, and the key caveat that a pending result is saved configuration rather than a running URL.

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?

Purpose and precondition are front-loaded and every sentence carries operational content (auth path, error code, side effects, refusal, pending-vs-running caveat). It is dense and runs long, but there is little filler to cut.

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 7-parameter mutating tool with an output schema already present, the description covers preconditions, permission model, error signaling, side-effect scope, and post-call verification ('check status') without needing to restate return values.

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 only 57%, and the description compensates for the two most consequential parameters: it explains that 'owner' must be a Tailscale login (beyond minLength:1) and that optional 'admins' can open all private apps. gateway/hostname/gateway_tag/gateway_ports are left to the schema, so coverage is meaningful but not exhaustive.

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 with scope: 'Enable an independent Tailnet-only home portal.' The 'Tailnet-only' and 'independent' qualifiers distinguish it from portal_disable and the portal_route_* siblings without the agent needing to open another schema.

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?

Clearly frames context: HTTP MCP requires the current exact portal owner, while local CLI/stdio MCP is the bootstrap/recovery path for an unset owner. It also states when-not boundaries ('Does not install or restart the daemon, send invites, or change tailnet ACLs'), though it never routes the agent to a named alternative sibling for those adjacent tasks.

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