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

Beyond the readOnly/idempotent annotations it discloses that no model is invoked and repeated calls over the same rows return identical numbers, that scoreWindow/coverage/truncation flags bound interpretation, and that scores are practice estimates with exams kept separate. The only weakness is mild repetition of the read-only/determinism point that annotations already cover, and no statement about response size or latency.

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 the return shape and usage triggers, which is good, but it is longer than needed and repeats itself: 'scores are practice estimates' and 'Saved scores are not official exam results' say the same thing, and 'scoreWindow and truncation flags bound their interpretation' restates an earlier limits sentence. One cleanup pass would remove roughly a third of the text without losing information.

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 has to carry the return shape, and it does by naming the sections and key fields (criterion averages, score history, bounded corrections, nextStepPlan, examScope, scoreWindow, truncation). What remains thin is the conditional nature of nextStepPlan ('for IELTS learners with a recent scored mock'), which is described but not bounded in size or shape.

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%, so the schema already documents both parameters and the baseline is 3. The description nonetheless adds meaning the schema lacks: the rolling window differs from a local-calendar preset, and examScope clarifies how the optional exam parameter influences whether totals are IELTS-only, CELPIP-only, or all attributable records.

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 ('Returns the signed-in learner's saved IELTS or CELPIP practice totals over a rolling window') and names the internal sections (Live Conversation, Recording Practice). It also positions the tool against adjacent capabilities by stating that speaking practice, recording, scoring and mock tests 'take place in Joe Speaking', 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 concrete triggering intents ('how practice is going, how to get a steady 7, which one to practise first today, or wants saved evidence for a study plan or band-consistency review'). It adds explicit boundaries: this rolling window is not the Dashboard local-calendar preset, and the actual practising happens in Joe Speaking, which routes the agent away when it wants action rather than evidence.

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