Ripostiq

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

Annotations only declare destructiveHint=false. The description adds meaningful behavioral context by specifying what the tool returns and the expected sequence (start, run intake, then teach). This goes beyond the annotation without contradicting it.

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 concise sentences, front-loaded with the primary action, and includes no filler. Every sentence adds value: the first states the action and outputs, the second gives the workflow.

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?

An output schema exists, so return-value details are covered. The description provides the essential workflow and return content. However, parameter semantics are thin, and the term 'intake' is introduced without explanation, leaving minor gaps. Still, it is mostly complete for a starting tool.

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 must compensate for parameter meaning. While 'course' is implicitly the course to start, the description does not clarify the expected format (e.g., course ID, slug) or the role of auth_token. The parameter semantics are largely undeveloped.

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 clearly states 'Start a course' with a specific verb and resource, and further distinguishes the tool by listing its specific outputs (tutor protocol, intake guidance, module map). It uniquely identifies this as the entry-point tool, setting it apart from sibling tools like start_exam or start_interview.

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 explicit workflow guidance: 'Call this first, run the intake, then call teach_section to teach Module 1.' This tells the agent exactly when to use it and even names the next tool to call, making the usage sequence unmistakable.

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?

Despite annotations only saying destructiveHint=false, the description adds meaningful behavioral details: the question is 'deterministic per day' and 'drawn from modules they've started,' and calling with done=true 'logs it and bumps the streak.' This discloses a state-changing side effect beyond the annotation. It lacks details on auth/errors but covers the core behavior well.

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 compact and front-loaded with the concept 'The two-minute drill.' It packs essential instructions into one sentence, though the run-on structure with semicolons could be clearer. Every clause carries information, so it earns a 4.

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?

The two-phase interaction is well explained, and an output schema exists, so return values need no description. However, the required 'course' parameter is completely undocumented, which is a significant gap. The tool's simplicity and output schema save it from a lower score, but it's only minimally complete.

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 description explicitly explains the 'done' parameter ('call again with done=true to log it') but provides no meaning for the required 'course' parameter or 'auth_token.' With schema description coverage at 0%, the description was expected to compensate but does not, leaving critical parameter semantics undefined.

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 clearly identifies the tool's purpose: 'today's spaced-recall question + the learner's day streak' with explicit actions 'Call it to fetch today's question' and 'call again with done=true to log it and bump the streak.' This distinguishes it from sibling tools like recall_questions by emphasizing the daily drill and streak mechanics.

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?

Provides clear step-by-step usage: first call to fetch, then after revealing the answer, call again with done=true. The 'daily habit' framing implies the intended use case. However, it does not explicitly contrast with alternatives or state when not to use the tool, so it falls 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: it returns 'full content', supports retrieval 'by id, or by key+course', and frames the artifact as a 'prior deliverable'. This goes beyond simply restating the tool's name.

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 action, resource, and lookup methods; the second gives a concrete use case. 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?

Given the tool's simplicity, the existing output schema, and the annotations covering safety, the description is complete. It covers what the tool does, how to invoke it (by id or key+course), and when to use it. No critical gap remains for an agent to select and use 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 0%, so the description must compensate. It usefully explains that artifact_id is an id-based lookup, while key+course form an alternative lookup path. This clarifies the relationship between three of the four parameters. auth_token is left unexplained, but its name and the context of a read operation make its purpose inferable.

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 'Fetch a saved Library artifact's full content' — a specific verb ('Fetch'), a clear resource ('saved Library artifact'), and the scope ('full content'). It also distinguishes from siblings like list_artifacts (listing) and submit_artifact (writing) by focusing on retrieving an existing artifact's content.

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 to pull a prior deliverable forward and build on it in a new chat,' which clearly indicates when to use the tool. It does not explicitly name alternatives or give when-not-to-use guidance, but the use case is strong enough to guide an agent.

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 and destructiveHint=false. The description adds meaningful context about how certificates are earned (boss battles passed) and where they are viewable/verifiable, enriching the behavioral picture beyond 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?

The description is concise (two sentences) and front-loaded with the core purpose. The structure flows logically from status to parameter guidance to verification context, though the phrase 'Ripostiq certificate status' is slightly awkward and could be clearer.

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?

Given an output schema exists, the description need not detail return values. It covers the key distinction between certificate types and earning conditions, but the lack of detail on `course` and `auth_token` parameters leaves minor gaps for invocation. Overall, it is sufficiently complete for a read-only tool.

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 description thoroughly explains the `module` parameter and its default behavior, but does not explain `course` or `auth_token`. With 0% schema coverage, the description only partially compensates for the missing 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 clearly states the tool retrieves certificate status, distinguishing between module and course certificates. It uses a specific resource (certificate) and explains the two modes, which separates it from sibling tools like get_progress or get_artifact.

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?

Provides explicit guidance on when to pass `module` (for a module certificate) vs omit it (for the course certificate), giving clear decision criteria. However, it does not explicitly mention alternatives or when not to use this tool, but the internal distinction is well covered.

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 this is read-only and non-destructive. The description adds authentication context (OAuth bearer or auth_token) and the 'across courses' scope, which is useful, but it does not disclose further behavioral details like pagination or empty-result handling.

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?

A single sentence that is front-loaded with the action and resource, with no unnecessary filler. Every word adds meaning.

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 an output schema and safety annotations, the description covers purpose and authentication adequately. It doesn't define 'entitlements,' but that is likely domain context and not critical for 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?

Schema coverage is 0%, so the description must compensate. It does mention auth_token and its relationship to OAuth bearer, but it doesn't explain token format, precedence, or how to obtain it. For a single optional parameter with a null default, this is adequate but minimal.

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 ('List') and identifies a precise resource ('logged-in account's entitlements across courses'), clearly distinguishing it from sibling listing tools like list_courses or list_artifacts. The scope is 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?

It clearly indicates when to use this tool: to list entitlements for the logged-in account. While it doesn't explicitly name alternatives or exclusions, no competing entitlement tool exists among siblings, and the auth method note adds useful context.

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 and destructiveHint=false, and the description adds behavioral value by explaining that paid modules require an active entitlement and that not-entitled responses return a {locked, teaser, checkout_url} shape. This goes beyond the structured annotations without contradicting 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?

The description is two tight sentences with no filler. It front-loads the primary action and then adds the entitlement outcome, ensuring every sentence 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?

Given the output schema exists and annotations cover safety, the description is largely complete: it states the resource, the access rule, and the fallback return shape. The main gap is the lack of parameter explanation, but that is already penalized in parameter semantics; overall, an agent can select and invoke the tool for common cases.

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 must compensate, but it does not explain any of the four parameters (course, module, section, auth_token). It only indirectly references 'module,' leaving the meaning and expected values of all parameters unclear.

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 verb+resource: 'Fetch a module's lesson content,' which clearly identifies what the tool does and distinguishes it from sibling tools like get_outline and get_recap. It also adds the entitlement context, making the purpose even more concrete.

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 implies when to use the tool—when a module's lesson content is needed—and provides an important condition: free modules are open, while paid modules require entitlement. It does not explicitly name alternatives or exclusions, but the context is clear enough for typical use.

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 and destructiveHint=false. The description adds that it 'marks locked modules and their progress,' which is useful behavioral context beyond what annotations provide. No contradiction exists.

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 a single, information-dense sentence with no filler. Every clause adds value: the content coverage, the purpose, and the behavioral trait of marking locked modules and progress.

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?

The presence of an output schema reduces the need to explain return values. The description covers content, purpose, and behavioral context. However, the lack of parameter semantics slightly detracts from overall completeness for an agent trying to select and invoke the tool 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 0%, and the description does not explain the 'course' parameter's format or acceptable values, nor does it mention the optional auth_token. It only implies that 'course' identifies which course's outline is requested, which is insufficient compensation for the missing schema descriptions.

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 clearly states that the tool returns the full course outline with every module and section title, and it gives the purpose: allowing the learner to pick any module/section to start. This specific verb+resource scope distinguishes it from siblings like get_lesson and list_courses.

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 implies when to use the tool by mentioning that the learner can pick any module/section to start in any order. It provides clear context but does not explicitly name alternative tools or exclusions, so it falls 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 readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by detailing the structure of the return value (raw doc, summary fields, wind_down coverage), which is more transparent than just saying 'get progress'. No contradictions; the read-only nature is preserved.

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 a single, information-dense sentence that front-loads the core action ('Return...') and then packs all key details without redundancy. Every phrase adds value, and it is well-structured with the dash and parentheticals for clarity, not wasted words.

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?

Given an output schema exists, the description does not need to enumerate return fields, but it adds valuable semantic context (e.g., what wind_down coverage means) and clarifies the tool's scope (per-module progress, boss status). It lacks operational details like how to pass the course identifier or auth token usage, but for a simple read-only tool with one required parameter, it is mostly complete.

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 input schema has two parameters (course, auth_token) with zero schema descriptions (0% coverage). The description does not compensate: it only mentions 'for a course' without explaining the format or meaning of the course parameter, and completely ignores auth_token. An agent must guess how to populate these fields, making this dimension severely lacking.

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 clearly states the tool's purpose with a specific verb ('Return') and resource ('learner's progress for a course'). It enumerates the exact components returned (raw doc, summary, per-module data, boss status, percent, position, wind_down coverage), making it easily distinguishable from sibling tools like get_recap or get_artifact.

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 clear context for when to use this tool: when a detailed view of a learner's course progress is needed, including raw data and a summary. It does not explicitly name alternatives or exclusions, but the distinct output details make the intended use case obvious relative to siblings.

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 and destructiveHint=false, and the description does not contradict them. It adds helpful behavioral context by specifying the tool is for returning learners and that it includes recall questions to reactivate memory, which goes beyond the safety flags.

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 a single, dense sentence with front-loaded purpose ('Resume briefing') followed by specific deliverables. Every clause adds value, with no wordiness or repetition.

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?

The description covers the tool's purpose, output contents, and a clear usage trigger (session start). Given that an output schema exists and annotations cover safety, the description is sufficiently complete for a relatively simple retrieval tool.

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%, and the description does not mention the 'course' or 'auth_token' parameters at all. While 'course' is reasonably inferable, the description fails to add any semantic meaning or usage detail for the parameters, leaving the agent to guess.

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 starts with a specific verb-phrase 'Resume briefing' and details exactly what it returns: coverage, mastery levels, strong/weak topics, and recall questions. It clearly distinguishes itself from siblings like get_progress or get_lesson by framing it as a returning-learner session-start resume.

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 instruction 'Call at session start' provides an explicit when-to-use signal. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when this tool is appropriate versus other retrieval tools.

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?

With only destructiveHint=false in annotations, the description adds valuable behavioral details: 'No login or course needed' and 'Returns the interview protocol + a course recommendation.' It also implies a non-interactive prep activity. It does not contradict 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?

The description is three sentences, front-loaded with the core purpose, and each sentence adds value. There is slight redundancy between 'realistic, calibrated' and 'real grilling,' but overall it is efficient and well-structured.

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?

Given that an output schema exists, the description does not need to detail return values, but it still mentions the return content. It covers the main parameters and usage context. The main gap is not explicitly distinguishing from start_interview or clarifying whether the interview is interactive vs. protocol-based, but this is partially addressed by mentioning 'returns the interview protocol.'

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 0%, so the description carries full responsibility for parameter meaning. It explains jd_or_skill, role, experience, and focus with examples (e.g., '5 years'), covering 4 of 5 parameters meaningfully. Only auth_token is left unexplained, but it is likely a standard auth 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?

The description states it is a 'realistic, calibrated interview for a role' and explicitly says it returns 'the interview protocol + a course recommendation,' making the tool's purpose clear. It is distinct from siblings like start_interview and daily_drill, though it does not explicitly name them as alternatives.

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 gives a clear usage context: 'Great when someone is prepping for an interview and wants a real grilling.' However, it does not explicitly state when not to use this tool or mention alternative tools such as start_interview, so it lacks exclusion criteria.

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 convey readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by disclosing output shape ('titles + metadata'), ordering ('newest first'), and scope ('the learner's saved Library artifacts'), which are not in 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?

The description is two concise sentences. The first sentence front-loads the core action and output details, and the second gives usage context. There is no redundant or filler content.

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?

Annotations and an output schema reduce the need to describe return values and safety, and the description does give a clear use case. However, the 0% schema coverage combined with no parameter guidance in the description means the tool cannot be reliably invoked without significant inference about the required 'course' and optional filters.

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%, and the description provides no parameter explanations. It does not clarify the required 'course', the optional 'type' and 'module' filters, or 'auth_token'. With four parameters and no schema descriptions, the description fails to compensate, leaving parameter semantics almost entirely unexplained.

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 'List' and identifies the exact resource: 'the learner's saved Library artifacts'. It adds output scope ('titles + metadata') and ordering ('newest first'), and it clearly distinguishes from sibling get_artifact, which retrieves a single artifact rather than a list.

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 states when to use the tool: 'Use at session start (with get_recap) to reference prior work and continue seamlessly.' This provides clear contextual guidance, but it does not explicitly state when not to use it or name alternatives like get_artifact, so it stops 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 readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: no login needed, the personalized behavior for logged-in users (authored courses marked `mine` with visibility), and the return of `course` id. It also communicates that the tool is safe to call without login. 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?

The description is four sentences, front-loaded with the core purpose in the first sentence. Each sentence adds value: usage guidance, course structure reference, return value, and a special case. There is no fluff or redundancy.

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?

Given the tool's simplicity (one optional param, output schema exists, annotations present), the description is complete. It covers what the tool does, when to call it, the output's role in the workflow, and the edge case for authenticated users. All essential context for an agent to select and invoke the tool correctly is included.

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 input schema has only one optional param (auth_token) with 0% description coverage, but the description clarifies its purpose: 'no login needed' implies the default behavior, and 'For a logged-in learner this also includes courses THEY authored' explains what happens when auth_token is provided. This fully compensates for the schema's lack of description.

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 explicitly states 'List every available Ripostiq course' with the specific verb 'list' and resource 'courses.' It distinguishes from sibling tools like list_artifacts and list_interviews by clarifying it is the entry point for browsing or starting learning, and mentions that it returns the `course` id for use with other tools.

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 explicit usage guidance: 'Call this FIRST when a user wants to browse or start learning.' It also describes the follow-up flow via begin_course(course) → teach_section, and notes the special case for logged-in learners where authored courses are included, providing clear context for when to use this tool.

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 and destructiveHint=false, and the description adds useful behavioral context: 'No login or course needed', the adaptive mock-interview structure, and the candid scorecard. This is more than enough for a read-only list tool.

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 front-loaded with the action and includes a compact example. The later sentences explain content and usage without padding, though the dash-heavy clause about question pairs is slightly dense.

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 no-parameter, read-only list tool with an output schema and annotations, the description covers purpose, content type, prerequisites, and the recommended next step. Nothing essential 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?

There are zero parameters and the schema coverage is 100%, so there is nothing to document. The description adds conceptual meaning about what the listed items are, which is sufficient for parameter 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 uses a specific verb ('List') and resource ('curated Interview-Prep topics'), with an example topic, making the action unambiguous. It also distinguishes itself from sibling tools by clarifying that this is the listing step before start_interview, rather than actually conducting an interview.

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 clearly states when to use the tool ('Call this when someone wants to prep for an interview on a topic the catalog covers') and points to the follow-up tool (start_interview). It does not explicitly discuss when not to use it relative to other siblings, so it misses the top score.

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?

The description goes beyond the minimal destructiveHint annotation by explaining the auth_token flow and explicitly warning against asking users to enter credentials in the chat for other connectors. It adds meaningful behavioral context about scope and limitations, though it does not detail side effects like token storage or session behavior.

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 concise, front-loaded with the primary purpose, and uses two focused sentences. Every sentence adds value, with no redundant filler.

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 login tool with an output schema present, the description covers the key contextual differentiator (Claude Code plugin vs web/desktop connector) and provides actionable guidance. It could be more complete by mentioning the outcome of the login or error handling, but the core usage context is well covered.

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?

With 0% schema description coverage, the description needed to explain the email and password parameters, but it only mentions them in passing while warning against using them on other connectors. It does not add meaningful semantics about how the parameters are used, expected formats, or relationship to the auth_token flow.

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 clearly states the tool's specific purpose: 'Claude Code plugin login only (auth_token flow).' It distinguishes this tool from the web/desktop connector login by explaining the different auth contexts, making it easy to select correctly among sibling tools.

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?

Explicit usage guidance is provided: this tool is only for Claude Code plugin auth_token flow, and for web/desktop connector, the user should be directed to the connector's OAuth login instead. This clearly states when to use and when not to use the tool, including specific 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 only include destructiveHint=false, so the description adds valuable behavior context: it says progress is stored server-side, appears on the account, and syncs across devices. It also clarifies accepted payload patterns. It does not mention auth requirements or reversibility, but covers the key behaviors for a non-destructive write operation.

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, front-loaded with core purpose, then compact usage guidance. Every phrase adds value with no redundancy or fluff.

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?

Given the tool has 7 parameters and an output schema, the description covers the main usage contexts (section completion, boss battle, lab change) and parameter patterns. It could mention auth_token and the required course/module fields more explicitly, but the description is sufficiently complete for an AI agent to use the tool correctly in typical scenarios.

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 has 0% description coverage, but the description compensates by explaining the semantics of section_id, boss ('passed'/'failed'), boss_attempt=true, and lab. Course and module are obvious from their names, and auth_token is the only parameter left unexplained. This is a solid compensation effort.

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-object pair ('Record the learner's progress server-side') and clearly explains the effect ('shows on their account + syncs across devices'). It distinguishes itself from siblings like get_progress which reads progress, while this tool writes it.

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?

Provides explicit when-to-use scenarios: 'Call when a section is genuinely completed (section_id), or after a boss battle..., or on a lab status change.' This gives clear context, though it does not explicitly mention when not to use or name alternative tools.

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 and destructiveHint=false, and the description adds the useful context that questions come from completed modules. However, it does not describe any additional behavior such as question ordering, randomness, or how the count parameter affects output.

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 a single concise sentence with no filler, front-loading the core action and source.

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?

Given the tool's low complexity, existing annotations, and output schema, the description is minimally adequate, but it lacks parameter explanations and usage guidance, leaving significant gaps for an agent to fill by inference.

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%, and the description fails to mention any of the parameters (count, course, auth_token) or their semantics. The agent must infer what 'course' and 'count' mean from names alone.

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 clearly identifies the action ('Return'), the resource ('spaced-recall questions'), and the source ('account's completed modules'), which distinguishes it from sibling tools like daily_drill or get_recap.

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?

No guidance is provided about when to use this tool versus alternatives such as daily_drill or get_recap; there are no exclusions or context clues beyond the general notion of spaced recall.

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 only provide destructiveHint:false. The description adds context about it being a single-session, no-login interaction that returns a roast protocol and course recommendation. However, it does not disclose data handling, privacy, or any side effects beyond output generation.

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 a single paragraph with a clear lead sentence, followed by practical parameter hints and a use-case statement. It is slightly dense with parentheticals but every sentence adds 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?

Given an output schema exists, the description appropriately covers what it returns (roast protocol + course recommendation), what it accepts, and when to use it. It lacks error case or rate-limit details, but these are not critical for a simple feedback tool.

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 has 0% description coverage, but the description explains work, kind, and focus with examples and intended purpose. Auth_token is not mentioned, but it is likely a system-managed credential. The description substantially compensates for the schema 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 clearly states the tool's function: 'a single tough-but-fair stakeholder grilling of ANY artifact' with varied examples. It distinguishes itself from siblings by emphasizing it's free, requires no login/course, and serves as an entry point for informal feedback.

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 notes 'No login or course needed' and recommends use as 'an entry point when someone wants honest, pointed feedback on real work.' This implies appropriate conditions but does not explicitly name alternative tools or exclusion criteria.

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?

Beyond the sole destructiveHint=false annotation, the description adds meaningful behavioral context: difficulty changes stakeholder intensity, the rubric stays unchanged, real stakes/earned PASS are involved, and the learner should get a choice first. It does not address auth_token or potential side effects, but the output schema likely covers return shape, making this a solid disclosure level.

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 compact and front-loaded with the core purpose, then efficiently explains the main knobs (difficulty, persona_style) and the invariant rubric. Phrases like 'real stakes, earned PASS' add a bit of flavor, but every clause carries meaningful information without excessive bloat.

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?

Given the bare schema and minimal annotations, the description covers the core usage scenario well: what boss battle is, gating, customization options, and the fact that rubric is unchanged. It could be more explicit about when to use this instead of get_lesson or start_exam, and auth_token is omitted, but overall it is sufficiently complete for a single-purpose action tool.

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?

With 0% schema description coverage, the description compensates by explaining difficulty values ('friendly', 'standard', 'brutal') and persona_style examples ('skeptical CTO', 'hostile board member'). However, it does not clarify the required course/module parameters beyond the phrase 'module's', nor does it mention auth_token, so the compensation is only partial.

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?

Clearly identifies the resource (the module's boss-battle simulation) and the action ('Get the module's boss-battle simulation + how to run it'), and the mention of gating/PASS distinguishes it from plain lesson tools. However, the verb 'Get' is slightly less direct than the tool's title 'Run boss battle', and the exact boundary with get_lesson could be sharper.

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?

'Gated like lessons' and 'Offer the learner the choice first' imply when and how to invoke the tool, while the difficulty levels provide context for tailoring. It does not explicitly name sibling alternatives or state when not to use this tool, so the guidance remains implicit rather than fully explicit.

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?

With only destructiveHint=false as annotation, the description adds extensive behavior: login/entitlement gating, needs_login/locked responses, form without answers, server-held key, and proctoring expectations. This far exceeds annotation coverage.

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 dense but every sentence adds value—no filler. It is well-structured with an em-dash flow that is readable despite the technical details.

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?

Despite minimal annotations, the description covers purpose, return values, gating, security restrictions, and the next step. It is self-contained and complete for a tool with a rich output schema.

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 has zero descriptions for parameters, and while the description mentions course in the workflow, it does not explicitly map auth_token to the gating behavior. Some compensation exists, but full parameter clarity is not provided.

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 clearly states the tool starts the course's scored practice exam, a specific resource and action. It distinguishes itself from siblings like daily_drill and submit_exam by emphasizing the scoring and full-length mock format.

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 provides a clear workflow: start the exam, collect letters, then call submit_exam(course, answers). It also gives an instruction on what not to do (never reveal answers), but does not explicitly mention when to avoid this tool in favor of an alternative.

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?

Beyond the sparse annotations (only destructiveHint: false), the description thoroughly discloses behavior: returns needs_login if not authenticated, returns a question bank plus an adaptive protocol with specific patterns (one question at a time, concept then scenario, hint when stuck, scorecard). This adds significant context about expected behavior and safety.

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 efficient, with each sentence contributing purpose, parameter clarification, behavioral notes, or next steps. It is not as minimal as the two-sentence ideal, but the extra context about login and the adaptive protocol is valuable and not redundant.

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?

Given the sparse annotations and 0% schema coverage, the description carries the full burden and covers all critical aspects: input source, authentication requirements, return value, and follow-up action. The output schema handles return structure, so no additional return-value detail is needed.

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?

With 0% schema description coverage, the description compensates by explaining that `interview` is a topic id from list_interviews and that `role`/`experience` calibrate difficulty. It does not explicitly describe auth_token, but the login requirement implies its purpose, giving meaningful semantic coverage beyond the raw schema.

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 'Begin a curated Interview-Prep session on a fixed topic', which is a specific verb+resource construction that clearly states the tool's function. It distinguishes itself from sibling tools like list_interviews (listing topics) and start_exam (exams) by focusing on starting a prep session.

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 provides clear context for when to use the tool, including that `interview` comes from list_interviews and that a login is required (with instructions not to run questions if not logged in). It also mentions saving with save_interview, but does not explicitly contrast with alternatives like interview_prep, leaving a small gap.

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 only cover destructiveHint=false, so the description adds meaningful behavioral context: it stores content in the Library with type='deliverable' and returns the module rubric. It also discloses the workflow expectation to call get_review next. It stops short of covering auth requirements or failure modes, but it goes well beyond the minimal annotation coverage.

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 sentences with no filler. The first sentence states purpose, the second explains the side effect and return, and the third gives workflow and alternative. It is front-loaded and every sentence 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?

The description is strong on purpose, workflow, and alternative, and the output schema covers return values. However, with 6 parameters and all schema descriptions absent, the lack of parameter-level guidance leaves a notable gap. The description is sufficient for selection but not fully complete for reliable invocation without further inference.

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 must compensate for undocumented parameters. It only clarifies that type is set to 'deliverable' and vaguely references a module rubric, but it does not explain the required course/module parameters or the optional repo_ref, auth_token, and content_text. This leaves significant ambiguity for invocation.

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 verb and resource ('Submit a lab deliverable'), then clarifies the unique behavior: stores as type='deliverable' in the learner's Library and returns the module rubric. It also distinguishes itself from note-taking via the save_artifact alternative, making it clearly different from siblings like get_artifact and list_artifacts.

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 states the follow-up action ('Call get_review next') and provides an explicit alternative for when not to use this tool ('For general note-taking use save_artifact instead'). This gives the agent clear when-to-use and when-not-to-use guidance.

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?

The description adds behavioral details beyond the annotation (destructiveHint: false), such as 'unanswered questions score as incorrect' and the return composition ('scaled score, PASS/FAIL vs the pass line, a per-domain breakdown, and the per-question rationale'). It also states an evaluative behavior ('Deliver it as an honest scorecard and point them to the weak domains' modules'). No contradictions 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?

The description is three sentences, each adding distinct value: what it does, how answers map, and what it returns plus a delivery guideline. No redundant phrasing, and the main action is front-loaded in the first sentence. It is appropriately sized without being verbose.

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?

The description covers prerequisites ('started with start_exam'), the input format, the scoring rule for unanswered questions, and the output components. However, it does not clarify how the specific exam attempt is identified (e.g., via `course` or if there is an implicit attempt reference), which is a notable ambiguity for a submission tool. Despite this, the presence of an output schema reduces the burden of explaining return values, so the description is largely complete.

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 must compensate. It thoroughly explains the `answers` parameter with a concrete example ('{"q001": "A", "q002": "C"}') and the rule for unanswered questions. It does not explain `course` or `auth_token`, but the latter is self-evident and `course` is a common identifier. The explanation of the most complex parameter is strong, so this earns a 4 rather than a 3.

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 clearly states the tool's function: 'Score a practice exam started with start_exam.' This specifies a concrete verb ('score') and resource ('practice exam'), and explicitly differentiates it from the sibling tool start_exam by pairing with it. The title 'Submit exam answers and score the attempt' reinforces this purpose.

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 clear context for when to use the tool: 'Score a practice exam started with start_exam.' This implicitly conveys that it should be used after start_exam and is the scoring counterpart in the workflow. However, it does not explicitly state when not to use it or mention alternatives (though there are none evident among siblings), so it misses the top score.

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?

With only destructiveHint=false in annotations, the description adds valuable behavioral context: it discloses the locked/teaser response for unpaid modules, the need to teach socratically, and the iteration pattern with section_index. It does not go into side effects or deeper details, but for a read-like teaching tool it provides enough transparency beyond the sparse annotation.

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 long, front-loaded with the primary purpose, and every clause adds value—the entitlement behavior, the pedagogical instruction, and the advancement pattern. There is no fluff or redundancy, making it an exemplar of concise, structured tool documentation.

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?

Given that an output schema exists and the tool is relatively simple, the description covers the core interaction flow (get section, handle lock, teach, advance). It does not enumerate all return fields, but the output schema covers that. The only minor gap is not specifying what happens at the end of a module or how to handle errors beyond locked/teaser, but overall it provides enough 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?

Schema description coverage is 0%, so the description must compensate. It partially does: 'section_index' is implied through '+1 to advance,' and 'module' is contextually referenced via 'Free module is open.' However, 'course' and 'auth_token' are left to name inference, and the exact range or format of section_index is not clarified. This is acceptable but not comprehensive.

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 clearly states the tool's function: 'Get one lesson section's content + the teaching protocol for it.' It uses a specific verb ('Get') and identifies a distinct resource ('one lesson section' plus its teaching protocol), differentiating it from siblings like get_lesson or get_outline. The mention of 'section_index' and advancement further clarifies its specific role.

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 practical guidance: it explains that free modules are open but paid modules need an active entitlement, and it instructs to 'Teach it socratically, then call again with section_index+1 to advance.' This implies a sequential usage pattern and sets expectations for when to call. However, it does not explicitly contrast with sibling tools or state when not to use it, which would be clearer.

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 and destructiveHint=false, and the description's 'Return' aligns with a read-only lookup. It adds value by explaining how identity is resolved (via OAuth bearer or an auth_token), which annotations do not cover.

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?

One sentence with the action front-loaded and no fluff. The parenthetical auth detail is compact and directly relevant.

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 one-parameter read-only tool with an output schema and safety annotations, the description covers the necessary behavioral context. It does not need to restate return values or elaborate on error conditions.

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 input schema has 0% description coverage, so the description must compensate. It mentions 'auth_token' in prose, but does not explain its meaning, optionality, or interplay with OAuth bearer, leaving the schema's default null as the only structural clue.

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 clearly states 'Return the current logged-in user', naming a specific verb and resource. It also adds the auth context (OAuth bearer or auth_token), which distinguishes it from siblings like login and get_entitlements.

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 implies use when the agent needs to identify the currently authenticated user, providing clear context without naming exclusions or alternatives. The auth-method note gives practical guidance on how the tool operates.

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