academy_tutor_context

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

With only readOnlyHint: true provided by annotations, the description carries the transparency burden, and it does add value by noting the response structure (lesson text, goals, level context) and the 'no Academy account needed' detail. However, it remains silent on edge behaviors like missing slugs, invalid levels, or response size, so it is adequate but not comprehensive.

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 description is two sentences with strong front-loading of the core purpose, followed by a compact usage signal. The parenthetical restates the tutor role slightly, but there is no wasted wording and the structure effectively separates 'what it is' from 'when to call 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?

Because there is no output schema, the description correctly bears the burden of describing the return value (lesson text, goals, level context) and does so acceptably. However, given the large sibling list, it fails to position itself against academy_lesson or academy_tutor, leaving ambiguity about when this tutoring-package variant is preferable, making this adequate but incomplete.

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 only 33%, so the description must compensate, yet it leaves 'slug' — a required string with no format hint — completely unexplained, missing the opportunity to point to a sibling list endpoint as its source. It only vaguely gestures at 'level context' and doesn't clarify how level (1-6) affects the result, so it fails to compensate for the coverage gap.

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?

The description uses a specific verb+resource combination: 'Get a lesson packaged as a tutoring brief: the full lesson text plus its learning goals and the level context,' which clearly states what the tool does. It is differentiated from sibling tools like academy_lesson through the tutoring-brief framing and the 'you are the tutor' role note, though it never names alternatives or explicitly contrasts, so it misses a 5.

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?

The description contains an explicit usage trigger — 'Call this when the user wants to be *taught* a lesson' — followed by clear role guidance for the agent. It establishes clear context but stops short of 5 because it gives no exclusions or named alternative tools (e.g., when to prefer academy_lesson or academy_tutor instead).

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