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

With no annotations, the description carries the full burden and does so well: it discloses the authorization requirement (admin only), the asynchronous side effect (balance rises only when Stripe confirms, not on call), the return value to hand off (checkoutUrl), and a named failure mode (PAYMENTS_UNAVAILABLE). This is rich, non-obvious behavioral context beyond a bare 'top up'.

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?

Three tight sentences, front-loaded with the audience constraint and purpose before the return-value handoff and failure mode. Every sentence adds a distinct, actionable fact with no repetition of schema content.

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 2-param mutation with no annotations and no output schema, the description covers purpose, auth, return value, async timing, and a failure code — essentially everything needed to invoke it correctly. Only minor gaps remain (e.g. whether repeat calls are idempotent or create separate checkout sessions).

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 description coverage is 0%, so the description must compensate. It adds real value for amountCentavos by giving the currency and human-readable range (₱500–₱50,000, matching the raw 50000–5000000 centavos bounds), but workspaceId is left entirely unexplained — the agent gets no clarification of which workspace's balance is topped up. Partial compensation warrants a 3.

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: 'start a card payment (Stripe Checkout) that adds amountCentavos ... to the prepaid balance.' An agent can immediately distinguish this money-adding action from siblings like billing_get (read) and platform_credits_grant (admin credit grant) 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 clear audience and condition ('Admin only, never an assistant') and the failure context ('Fails PAYMENTS_UNAVAILABLE when this deployment takes no payments'), so an agent knows when it applies and when it will error. It does not explicitly name the alternative (e.g. platform_credits_grant) for adding balance by other means, so it stops short of a 5.

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