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

Goes beyond readOnlyHint=true by asserting 'charges nothing and never starts a paid checkout' and by disclosing an OAuth scope requirement ('commerce connections must explicitly grant Nevermined credits') — both are non-obvious behavioral facts. Minor deduction because part of the no-side-effect claim restates the annotation, and the clause about switching on/resuming automatic top-ups is ambiguous about whether the tool or the human's dashboard action causes it.

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 the no-charge guarantee are front-loaded, but the sentence about topUpAvailable is a run-on with a tangled relative clause ('which also switches on automatic top-ups or resumes paused ones') whose referent is unclear. Information density is high but readability suffers.

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?

With no output schema, the description carries the burden of explaining returns and does so (topUpAvailable, dashboardUrl, reset date for existing subscribers), plus the follow-up workflow and auth requirement. It stops short of describing the full payload or what is returned when no subscription exists.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate; it instead spends its words on return fields (topUpAvailable, dashboardUrl, reset date). Correctly silent on parameter syntax because none exists.

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 — read the personal subscription balance and return the human's subscribe/manage link — and separates itself from sibling tools by name (get_budget, pay_service). An agent can tell this is a read of subscription state, not a purchase, without opening any 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?

Gives a clear trigger ('when credits are short'), a post-checkout workflow ('use get_budget to verify the credits, then retry pay_service'), and an auth prerequisite. It does not explicitly exclude or contrast the sibling top_up_credits tool, so the agent must infer that distinction from the dashboard-based wording.

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