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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it mandates an Authorization: Bearer hodds_... header and names the exact failure mode (token_required), and it explains billing semantics — one free watched solution, €0.50 each thereafter, €2 monthly minimum, billed if active at least one day of the period. It does not say whether past-due states block other operations, which would have pushed this to a 5.

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?

The return values are correctly front-loaded, but the middle is a dense run-on bundling pricing, VAT terms, invoicing, contract version and per-agent billing rules into one clause-heavy sentence. Much of the pricing detail is relevant context yet is delivered without structure, making the description harder to scan than its length warrants.

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 an output schema present, the return shape is already covered, and the description still usefully names the plan states and auth requirement. Given zero params and full annotation coverage, an agent has everything needed to call it correctly; only the ambiguity against get_creator_plan leaves a 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 tool takes zero declared parameters, so the baseline is 4. The description still adds meaning by disclosing an out-of-schema requirement: the organisation token must be supplied as a bearer header or the call fails with token_required — information the empty input schema cannot convey.

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 opens with a specific verb and resource — 'Returns the plan of the organisation of the token' — and enumerates the possible plan states (FREE, PAID, PAST_DUE, ENDING, ENDED) plus the billing artifacts returned. It is clear what the tool does, but it never disambiguates from the sibling get_creator_plan, which reads like a near-twin.

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?

Usage is only implied: an agent infers you call this to read the current subscription state. There is no explicit when-to-use, no statement of when to prefer get_creator_plan or cancel_plan, and no note that this is the read path before a cancellation. The one concrete constraint given — an organisation token is required — is behavioral rather than selection guidance.

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