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

Annotations already mark it readOnly/non-destructive, and the description reinforces this with 'Free: this read spends nothing' — consistent, not contradictory. It adds behavior the annotations cannot: how credits are scoped per billing system (modular vs legacy/Shopify organization-wide pools that must never be summed), that unlimitedScheduling nullifies credit consumption, that postLimit is null on modular billing, and that this is a planning snapshot rather than an authorization check.

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?

Front-loads the trigger condition before the billing nuance, and every clause is substantive. It is nonetheless long for a single-parameter read tool, and the instruction to 'read billingSystem, scope and unlimitedScheduling first' is slightly ambiguous about whether those values come from this call or from get_account.

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?

Output schema exists, yet the description still summarizes the payload (credits, allowance, reset, postLimit) so an agent knows what it will get. Given the genuine complexity of multiple billing models, it supplies the interpretation rules an agent needs to avoid misreading the numbers, and the annotations cover the safety profile.

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 100%, and the schema already explains that accountId comes from list_accounts, so the baseline is 3. The description adds real meaning beyond that: it explains the account-scoping consequence (legacy/Shopify accounts share one pool and report identical numbers) and prescribes asking the user when multiple accounts exist, which materially affects how accountId should be chosen.

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 (returns/reports) and resource (remaining credits, monthly allowance and reset date, post allowance) rather than restating the name. It distinguishes itself from get_account/list_subscriptions by framing the output as a credit-and-post planning snapshot, and names related actions (connect_feed, scheduling Pins) that consume the resources it reports.

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 explicit when-to-use conditions: before any credit- or post-consuming action, especially bulk ones, or when the user asks how many credits/posts remain and when they refill. It also gives an explicit procedural guardrail — ask the user which account when list_accounts returns more than one — rather than letting the agent pick.

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