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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'reads no legal text and changes nothing', adding the useful nuance that it does not read corpus content. It does not say whether the call itself counts against the daily allowance it reports, which is the one behavioral fact an agent pacing a long task would still want. No contradiction with annotations.

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-loaded with what it reports, then usage, then alternatives — a sensible order with no filler sentences. The opening sentence is a long enumeration, but every listed item is a distinct return value the agent would otherwise have to discover by calling it.

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?

There is no output schema, so the description carries the return payload, and it does so by naming the fields the agent gets back. Combined with the fully documented single parameter and the read-only annotations, an agent has everything needed to call it correctly and interpret the result.

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 100% and the single `session` parameter is fully documented there, including the omit-case for OAuth/key connections, so the baseline is 3. The description adds only 'Example arguments: {}', which signals the call is argument-free but does not restate the session semantics it might have reinforced.

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 subject and enumerates exactly what is returned: connection status, email, usage against daily limits, jurisdictions with a corpus, newest data dates, and workflows. It also names the siblings it is not (avokata_account for plan/limits/keys, describe for corpus contents), so an agent can distinguish it 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 an explicit trigger ('check sign-in or the remaining allowance before a long task') and routes two adjacent needs to their correct alternatives by name. Nothing about when to prefer this tool over avokata_account or describe is left to inference.

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