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

Annotations already cover readOnly, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description still adds real context beyond them: the billing:read scope, that billing reads cost 0, that it requires the caller's own Fonciq API key, that results vary by test/live mode, and that month boundaries follow Toronto time.

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 endpoint and the core purpose are front-loaded, which is good. But the entire content is then restated in French without adding new information, and 'Billing reads cost 0' is effectively repeated ('Les lectures de facturation coûtent 0'), which inflates length for a zero-parameter tool.

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 parameters and no output schema, the description carries the burden of describing what comes back, and it does: wallet balance by mode, Toronto-month usage from the platform ledger, and the OAuth daily cap when applicable. Only the sibling-level routing (billing_get vs billing_usage) is left thin.

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 there is nothing for the description to disambiguate and the baseline is a 4. The description wisely spends its words on response scope (balance, monthly ledger usage, OAuth daily cap) rather than inventing parameter guidance.

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 concrete resource and scope: 'Fonciq platform prepaid balance and this month's API usage', with an explicit negative boundary ('not Registre foncier fees') that separates it from the registry-billing siblings. It does not name the closely related siblings billing_get or billing_usage, so an agent must infer the split from the wording alone.

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 implied by the scope statements ('this month's API usage', 'current test or live mode', 'not Registre foncier fees'), which hints at when this is the right read versus registry billing. However, there is no explicit when-to-use/when-not statement naming billing_get, billing_usage, or any preconditions for calling this instead of those.

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