academy_tutor

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

No annotations exist, so the description carries the burden. It usefully discloses Pro-plan gating, sign-in requirements, and that the tutor is server-side with lesson context. It does not go further into error behavior or side effects, but for an AI-tutor query tool, the key constraints are made visible.

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 three short sentences and every clause earns its place: action, context, plan restriction, sign-in, and free alternative. It is front-loaded, scannable, and contains no filler or redundant restatement of the tool name.

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 simple query-style tool, the description conveys the purpose, the Pro/sign-in constraints, and the relevant sibling alternative. It also hints at lesson context via 'knows the lesson context.' It is less complete on the required level parameter and does not describe possible output, but the overall invocation context is clear enough for an experienced agent.

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 carries the full burden for parameter meaning. It implies that 'message' is the question to the tutor and 'lessonSlug' relates to lesson context, a helpful cue. However, it does not clarify the required 'level' parameter, which is not self-evident beyond being a 1-6 number. The description adds almost no explicit parameter-level semantics.

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 opens with a specific action, 'Ask the Academy Pro AI-Tutor,' and immediately distinguishes it from the sibling academy_tutor_context via 'For free self-tutoring use academy_tutor_context instead.' It also states the Pro plan restriction and server-side lesson context, making the tool's purpose and scope unambiguous.

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 explicitly says when to use the tool ('Pro plan only,' 'server-side, knows the lesson context') and explicitly tells the agent to use academy_tutor_context instead for free self-tutoring. It also flags authentication requirements with 'Requires sign-in.' This is strong usage guidance.

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