SuperȘcoala

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds useful behavioral detail beyond annotations by specifying output ordering ('curriculum order'), included URLs, and free/subscription flags, making what the caller receives predictable.

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?

Two dense sentences with no filler. Return contents are front-loaded, and the usage scenario follows immediately, earning every word.

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 read-only, idempotent one-parameter tool with no output schema, the description fully covers what the caller gets (full structure, chapters, lessons, URLs, flags) and how to use it, leaving no critical gap.

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% and the single required parameter course_id is already documented as 'Course (grade) id, from list_subjects.' The description does not need to add parameter-level detail; the schema carries the burden.

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 ('Returns') and resource ('the full structure of one grade (course)') and enumerates exactly what is included: subject, chapters in curriculum order, lessons, canonical URLs, and flags. It also distinguishes itself from get_lesson by positioning the output as a means to pick a lesson id.

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?

It explicitly states when to use the tool: 'Use it to see what a grade covers or to pick the lesson id for get_lesson.' This gives clear context, though it does not state explicit when-not-to-use scenarios relative to other siblings like search_lessons.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds behavioral value by specifying that the transcript is only returned for free lessons and listing the full set of returned fields, which is context not present in the annotations. This goes beyond baseline and provides agents with concrete expectations about the response contents.

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 no filler. The first sentence front-loads the primary purpose and enumerates return fields efficiently, while the second sentence gives actionable usage guidance. Every word earns its place, making it concise and easy to parse for an agent.

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 single-resource getter with one parameter, the description is thorough: it lists all returned fields, notes the conditional transcript for free lessons, provides usage context, and states the source of the identifier. The annotations already cover safety and idempotency, and there is no output schema, so the description fully equips an agent to call the tool 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?

The schema already provides 100% coverage for the single parameter lesson_id, including its source ('from search_lessons or get_course_outline'). The tool description reinforces the link to search_lessons but does not add any new semantic detail beyond what the schema already states. Per the calibration rule, baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 ('Returns') with a specific resource ('public details of one lesson') and enumerates the exact fields returned, which clearly distinguishes it from siblings like search_lessons and get_course_outline. It also explicitly positions it as the follow-up to search_lessons, making its unique role 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 gives a clear usage context: 'Use it after search_lessons to answer questions about a specific lesson.' It tells the agent when to call this tool and implies it is for detail retrieval after a search. However, it does not explicitly state when not to use alternatives like get_course_outline, so it stops just short of a 5.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the description need not repeat safety. It adds behavioral context by enumerating what the returned information covers (audience, formats, exam prep, public vs. subscription, SuperAI, certificates, contact). It does not describe the response shape, but for a simple profile retrieval that is a minor gap.

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?

Two sentences with no filler. The first sentence front-loads the primary behavior and the information domains; the second sentence gives the intended use. Every clause contributes value.

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?

This is a simple, no-required-parameter retrieval tool with a fully documented optional enum. The description tells the agent what the tool returns, covers the main content areas, and states when to use it. Nothing essential is missing for correct invocation.

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 single optional parameter, section, is fully documented in the schema with an enum and description. The tool description does not add extra meaning about the parameter, but the schema coverage is 100%, so a baseline score of 3 is appropriate.

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 ('Returns') and clearly identifies the resource: a profile of what SuperȘcoala is, including audience, grades, formats, and subscription boundaries. It is distinct from the sibling tools, which target courses, lessons, packages, subjects, teachers, and searches.

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?

It explicitly states the intended use: 'Use it to describe or recommend the platform.' This gives clear context for when an agent should call it, though it does not explicitly contrast it with sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the 'web' availability and return fields, but discloses no additional behavioral traits such as auth needs, rate limits, or pagination, which are not critical here. The description does not contradict the 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?

Two sentences with zero wasted words: the first states the resource and return contents, the second gives the usage trigger. The most important information is front-loaded.

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 read-only listing tool with one optional, well-documented parameter and no output schema, the description is complete: it lists the return fields, states the usage context, and annotations cover side-effect safety. Nothing an agent needs to call it correctly is missing.

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 optional 'period' parameter already has an enum and a clear description ('Return only the plans billed with this period'). The tool description adds no extra meaning about the parameter, so the baseline 3 applies.

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 ('Returns') tied to a concrete resource ('SuperȘcoala subscription plans available on the web') and enumerates the exact data fields returned. It clearly distinguishes this pricing/subscription tool from the educational-content siblings like list_subjects, list_teachers, and get_lesson.

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?

It explicitly states when to use the tool: 'Use it when someone asks what access costs or what a plan covers.' It does not explicitly name alternatives or exclusions, but none of the sibling tools overlap in purpose, so the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that the result includes canonical page URLs and ids, but doesn't mention ordering, pagination, or any other behavior. Given the annotations, the description adds modest context beyond them.

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?

Two sentences with no fluff. The core purpose is front-loaded, followed by a clear usage directive. Every word earns its place.

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 read-only list tool with one optional parameter, the description covers what it returns and how to use it. Annotations handle safety, no output schema exists, and nothing essential is missing for an agent to call it correctly.

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% (subject_id has a description), so the schema fully documents the parameter. The description doesn't add any extra meaning about the parameter—it only mentions return content, not parameter semantics. Baseline 3 is appropriate when the schema covers the parameter.

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?

Description clearly states the tool returns the full catalogue of school subjects with grades, URLs, and ids. It specifies the resource (subjects) and the action (list/return), and distinguishes itself from siblings by framing it as the discovery step for ids needed by search_lessons and get_course_outline.

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?

Explicitly instructs the agent to use it first to discover subject/course ids needed by other tools. This provides clear when-to-use guidance and implies the workflow sequence, though it doesn't state when not to use it, the direction is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable context by specifying the content of the return (summary and background presentation) and the scope (teachers who create the lessons), which goes beyond what annotations provide.

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 zero waste. The primary purpose is front-loaded, followed by a direct usage cue. Every word earns its place, and it is appropriately sized for a simple list 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?

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool returns and when to use it. No additional information like pagination or ordering is necessary for an agent to call it correctly, and annotations cover the operational safety.

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 schema description coverage is 100%, with the single optional 'name' parameter fully documented in the schema ('Return only teachers whose name contains this text'). The tool description does not add any additional parameter details, so it meets the baseline of 3 for high schema coverage.

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 states a specific verb ('Returns') and resource ('the teachers who create the SuperȘcoala lessons'), and also describes what is included (a short summary and a longer presentation of their background). This clearly distinguishes it from sibling tools that handle courses, lessons, packages, subjects, or platform info.

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 'Use it when someone asks who teaches on the platform or how qualified the authors are,' providing clear when-to-use guidance. It doesn't mention alternatives or exclusions, but given the sibling list, this is the only teacher-focused tool, so the context is sufficient without explicit alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return fields and search scope, which is useful, but it doesn't disclose deeper behavioral traits like pagination, empty-result behavior, or filtering semantics. This is adequate but not rich.

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 no fluff. The first sentence states the action and result; the second provides a clear use-case trigger. It is front-loaded and every clause earns its place.

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 search tool with no output schema, the description provides a clear purpose, expected return fields, and an explicit use case. The schema covers all parameter details, and annotations cover safety. It lacks only an explicit pointer to sibling tools for known-ID lookups, but overall it gives an agent enough to select and invoke it correctly.

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%, so the parameters (query, limit, course_id, free_only, subject_id) are already well documented. The description adds no additional parameter semantics beyond 'by keyword', which maps to the query parameter. Baseline 3 is appropriate when the schema handles parameter documentation.

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 and resource: 'Searches the SuperȘcoala catalogue by keyword' and details exactly what is returned ('matching Romanian K-12 lessons with their canonical page URL, subject, grade, chapter and free/subscription flag'). This clearly distinguishes it from siblings like get_lesson, which implies fetching a single lesson, and get_course_outline, which implies a structural view.

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 provides an explicit trigger: 'Use it whenever a student, parent or teacher asks for a lesson, worksheet or test on a topic.' This gives clear context for when to invoke the tool. However, it does not mention when not to use it or name alternatives such as get_lesson for known lesson IDs, so it stops short of the highest bar.

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