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

Beyond the annotations, it discloses two things an agent could not infer: the URL is bearer-owned (a credential that grants access to whoever holds it), and the tool itself never moves money, with the mutation happening in the human's browser session. This usefully reconciles the read-shaped behavior with readOnlyHint=false, though it says nothing about expiry or whether a new portal session is minted per call.

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 returned artifact, then the safety scoping. Nothing is padded and nothing needs to be re-read.

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 return values need no explanation, and the one-parameter surface keeps complexity low. However, the sole parameter is undocumented in both schema and description, and the absence of any routing cue against create_checkout_link leaves a real gap.

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?

The single parameter account_id has 0% schema description coverage and the description does not mention it at all, leaving ambiguous whose account it is and what form the identifier takes. The word "bearer-owned" gestures at ownership but does not pin down the parameter's meaning.

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?

"Return a bearer-owned Stripe-hosted billing-portal URL" gives a concrete verb (return) and resource (billing-portal URL) with an important qualifier (Stripe-hosted). It is adequately distinct from create_checkout_link by resource name, though it never names that sibling to draw the line explicitly.

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 human manages or cancels there" implies the use case: hand the URL off for self-service billing management. But there is no explicit when-to-use versus create_checkout_link, no prerequisites stated, and no conditions under which an agent should prefer subscription_status or get_plan.

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