Fiveable for AP Students

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond this: it explains that the tool also describes the weighting, that omitting sectionScores lets users discover section point maximums, and that the operation is computationally cheap. 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 two concise sentences with no filler. It front-loads the core function, then immediately gives the essential usage pattern, and closes with a one-word cost signal. 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?

For a read-only, idempotent calculator with a full output schema and 100% parameter coverage, the description is complete. It explains the discovery-then-predict loop, the weighting explanation, and cost characteristics. Nothing needed to correctly invoke the tool 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%, so the schema already documents subjectSlug, intent, and sectionScores thoroughly. The description adds a useful high-level workflow for sectionScores ('Call with no sectionScores to see which sections the subject has'), but this mostly mirrors the schema's own guidance to 'Omit to discover the subject's card structure first.' Thus the description adds only marginal value beyond the 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 a specific verb and resource: 'Predicts a 1-5 AP score from raw section scores using Fiveable's per-subject score calculator.' This clearly distinguishes the tool from siblings like score_frq_response or get_scoring_result, which handle different scoring workflows. The title 'Predict an AP score' reinforces a singular, unambiguous 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 an explicit two-step workflow: call with no sectionScores to discover the section structure, then call again with actual scores. This is strong usage guidance, though it does not name alternative tools or conditions for choosing a sibling, so it stops short of full exclusion 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds value by explicitly stating the non-persistence behavior and the anonymous-preview capability. 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 concise sentences with no filler. The first sentence delivers the core action and output, and the second sentence isolates the most important behavioral caveat about saving 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?

Given the simple operation, full schema coverage, existing output schema, and read-only annotations, the description covers the essential context: what it checks, what it returns, and how it behaves regarding saved progress. Nothing critical 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%, with all three parameters already documented, including answer format and questionId source. The tool description adds no new parameter-specific meaning beyond what the schema provides, so the 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 states a precise verb ('checks'), a specific resource ('one multiple-choice practice answer'), and the expected result ('returns correctness plus the Fiveable explanation'). It also distinguishes itself from a progress-saving submission path by explicitly noting it does not save progress.

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 indicates this works during an anonymous preview and does not save progress, while noting that a signed-in answer submission is required for saved progress. It does not explicitly name submit_practice_answer as the alternative, but the boundary is clear enough for an agent to route correctly.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds useful behavioral detail beyond that: it does not expose questions/answer keys, finalize timers, repair grading, start, autosave, or submit work. This gives the agent a precise understanding of side-effect and content boundaries.

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?

Three sentences carry a dense but purposeful amount of information, with the main action and scope front-loaded. The negative action list is somewhat long but earns its place by clarifying behavioral boundaries that annotations do not fully express.

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 presence of an output schema and safety annotations, the description covers the essential selection and invocation context: what is read, what is not exposed/mutated, and where the publicationId comes from. It could be slightly clearer about how the 'policy-selected owned attempt' is determined, but it is sufficient for correct tool use.

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%, and the description compensates by explaining that publicationId must come from the connected student's assignment listing and refer to an owned attempt. This adds meaningful context beyond the raw schema pattern, though it does not elaborate on failure cases or validation beyond the 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 names a specific verb ('Reads') and a specific resource ('one student-accessible publication's instructions, section counts, timer/due-date settings and released feedback'), making the tool's purpose immediately clear. It also distinguishes itself from related getters by explicitly stating that it does not expose questions or answer keys.

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 clear context: the tool operates on a publicationId from the connected student's assignment listing and on the policy-selected owned attempt. It provides negative boundaries by listing actions it does not perform, but it does not explicitly name sibling alternatives or state 'when not 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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavior beyond them: image-only pages are never guessed at, unavailable artifacts fall back to the approved PDF link, and the read never triggers processing. Return format specifics are left to the output schema.

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?

Three tightly packed sentences with no filler, front-loading what the tool does and following with fallback behavior. Slightly dense but 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?

An output schema exists, so return values needn't be re-explained, and the safety profile comes from annotations. What is missing is prerequisite context (where cheatsheetId comes from) and any parameter guidance for a 0%-coverage schema, leaving the definition adequate but not 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% and three parameters are required, so the description must carry the load. 'Bounded pages' gestures at page/limit semantics but never explains the cheatsheetId format (cs_ + 24 hex chars), the 1-32 page range, the 1-3 limit cap, or why limits exist. The schema alone leaves an agent guessing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Reads bounded pages from a prepared official Fiveable PDF') and specifies the distinctive output (page citations, extracted text, page images). It is clearly distinguishable from the sibling list_cheatsheets, which enumerates rather than reads 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?

Usage is implied by the name and the pixel-level output described, but the description never says when to prefer this tool over siblings like get_study_guide or get_guided_notes, nor does it state that a cheatsheetId must first come from list_cheatsheets. Adequate but with a clear routing 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 already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds a genuinely useful non-obvious trait not in structured data: the quota cost ('One call consumes one full-content preview for a caller without existing access'). It does not cover caching or pagination behavior, but the budget disclosure is real added value.

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?

Three tight sentences with no filler, front-loading what is returned before the usage hint and the cost caveat. Slightly terse rather than over-specified, but 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description closes the main remaining gaps (intended narrow use, quota consumption) though it leaves the two undocumented numeric parameters and sibling routing unaddressed.

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 67%, with query, intent, guideSlug and subjectSlug documented in-schema while maximumTokens and maximumSections carry only defaults. The description's 'one question' and 'small set' loosely gesture at the query and section limits but add no format or limits detail beyond the schema, 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?

States a specific verb and resource ('Returns ... Fiveable study-guide passages') and scopes it with 'relevant to one question' and 'a small set'. This is clear, but it never differentiates itself from close siblings like get_study_guide or search_content, leaving the agent to infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives usable scenarios ('narrow explanations, research questions and checking student notes'), which implies a narrow-lookup role versus broad retrieval. However it names no alternative tool and states no explicit when-not condition, so the routing decision against siblings remains implicit.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond those annotations: in-progress sessions return progress and the current question without answer keys, while completed sessions return the summary and recommendations. This fully discloses the conditional behavior of the 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 two sentences with no filler. It front-loads the core action and resource, then adds conditional detail that directly affects agent behavior, making every sentence valuable.

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 diagnostic tool, the description covers the essential states: in-progress and completed. It provides enough context for the agent to select and invoke the tool, especially since an output schema exists to define the actual response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not add parameter-level meaning beyond the schema. The intent parameter is well-documented in the schema, and sessionToken is semantically self-explanatory with a UUID format, but since schema description coverage is only 50% and the description does not compensate for the undocumented token parameter, the score stays at a baseline 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 opens with a specific verb and resource: 'Reads an owner-scoped Fiveable diagnostic.' It then distinguishes in-progress from completed sessions, making the tool's behavior clear and differentiating it from general exam or practice-result 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 clear context for when to use the tool: when retrieving diagnostic status or results, with distinct behavior for in-progress versus completed sessions. It does not explicitly name alternative tools or state when not to use it, but the diagnostic-specific scope provides adequate 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?

Annotations already mark the tool as read-only and idempotent, and the description adds meaningful behavioral context: progress continuation links require progress:read consent, only server-saved links are included, and browser-only progress is unrecoverable. This goes beyond the structured annotations and helps the agent set accurate expectations.

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?

Three sentences, each earning its place: one defines scope, one gives usage guidance, one discloses limitations. No filler or repetition of schema 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?

The tool has an output schema, so return-value details are not required. The description covers purpose, parameter usage, access/consent requirements, and data limitations, making it fully adequate for an agent to decide when and how to invoke it.

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 carries the burden for both parameters. It explains subjectSlug's role ('choose a subject for version choices') and unitNumber's role ('verify that unit's current bank and standard format'), adding meaning beyond the bare schema types. It could be more concrete about valid subject values and version choices, but it compensates reasonably.

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 names a specific verb ('Find') and a precise resource: Fiveable exam formats, access requirements, and website links. It explicitly excludes questions and answer keys, which distinguishes it from sibling tools like get_practice_questions and get_frq without needing to open schemas.

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 actionable guidance: choose a subject for version choices, and add unitNumber to verify that unit's bank and standard format. It does not explicitly name alternatives, but the 'without questions or answer keys' constraint clarifies when this tool is not appropriate.

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 mark the tool as read-only, idempotent, and non-destructive, and the description reinforces this with 'safely check' and 'never unfinished scores or feedback.' It adds valuable edge-case transparency around pending/partial grading and the honors practice reset limitation, going well beyond what the annotations alone 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?

Two tightly packed sentences front-load the core operation before addressing edge cases. Every clause adds meaningful information, with no repetition of the title and no 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?

The description covers invocation modes, identifier constraints, result availability behavior, and the honors-practice limitation. Combined with the existing output schema and read-only/idempotent annotations, an agent has everything needed to invoke this 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?

With 0% schema description coverage, the description carries the full semantic burden and succeeds: it explains when to use attemptId versus submissionId and enforces the mutual exclusivity rule with 'Supply exactly one.' It also conveys the ownership condition ('owned completed exam') that the raw schema cannot express.

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 'Read' and clearly scopes the tool to 'an owned completed exam' via attemptId or 'a submitted exam' via submissionId, establishing two distinct invocation modes. It also adds non-obvious behavioral details about pending/partial grading and honors practice, which further defines what the tool does and does not return.

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 instructs the agent to supply exactly one identifier and maps each parameter to its appropriate scenario: attemptId for owned completed exams and submissionId for submitted exams. It also warns that pending or partial grading returns status only, preventing unrealistic expectations. It does not name alternative sibling tools, but the usage context is clear.

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 discloses a side effect: 'It consumes one full-content preview unless existing access covers this FRQ.' This contradicts idempotentHint=true, since repeated calls without access would consume additional previews. Although it also adds useful cost context, the contradiction rule requires a score of 1.

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?

Three sentences: what is returned, why it matters for scoring, and the cost/access consequence. Every sentence earns its place and the key operation 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?

An output schema exists, so return-value details need not be repeated. The description covers the prompt contents, eligibility for scoring, preview consumption, and token cost, which is complete enough for an agent to decide whether and how to call it.

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%, with frqId described as coming from list_frqs and intent having a privacy-safe enum and instruction. The description adds no parameter-specific meaning beyond the schema, 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 opens with a specific verb and resource: 'Returns one full, original Fiveable FRQ prompt' and specifies the content (stimulus, background, lettered parts with point values). This clearly distinguishes it from siblings like list_frqs and get_frq_attempt_history.

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: the returned prompt is intended for Fiveable's saved scoring workflow after a response is written, and the consumption warning tells the agent to consider access before calling. It does not name alternatives or state when not to use, so it lacks explicit exclusions.

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. The description adds meaningful context beyond the annotations: the data is scoped to the signed-in student, and it represents past attempts for a single FRQ. This gives the agent a concrete sense of the returned data's semantics without conflicting with the annotation hints.

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, front-loaded sentence that first states the verb and resource, then the intended use case. Every clause earns its place, and there is no wasted verbiage or repetition of schema 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?

The tool is simple, has full schema coverage, and an output schema exists, so return values do not need to be explained. The description covers what the tool does, for whom, at what scope, and why it is useful, leaving no practical gap for an agent selecting or invoking it.

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 schema already documents frqId and intent thoroughly. The description's mention of 'a single FRQ' aligns with frqId but adds no new meaning beyond the schema. Baseline 3 is appropriate since 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?

States a specific verb ('Returns'), a precise resource ('the signed-in student's previous attempts at a single FRQ'), which clearly separates it from broader history tools like get_my_practice_history. The phrase 'single FRQ' adds an important scoping detail that disambiguates this from sibling tools even without naming them.

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 it: 'compare a new response against what they wrote before and comment on improvement.' It does not explicitly name alternative tools or state when not to use it, but the intent is clear enough for an agent to select it appropriately.

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. The description adds the cost/latency note ('Cheap — usually under 1k tokens') and clarifies the tool returns exactly one term's data, which is useful behavioral context beyond the annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences with zero fluff. It front-loads the core function, then the use case, then a cost hint. Every sentence earns its place and no redundant information appears.

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, full schema coverage, and an output schema, the description covers purpose, trigger, and cost. It doesn't explicitly discuss when not to use it (e.g., for listing multiple terms) but that's a minor gap. Overall it's sufficient for an agent to call 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%, with each parameter already documented (intent enum, termSlug, subjectSlug). The description does not add parameter-specific semantics beyond what the schema provides, so the baseline 3 applies. It doesn't detract, but it also doesn't enhance.

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: 'Returns the full definition, context and related terms for one AP key term.' It clearly distinguishes this from list_key_terms by emphasizing 'one AP key term' and ties to a concrete use case ('what does X mean'), making the tool's purpose 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 an explicit trigger condition: 'Use when a student asks "what does X mean" for AP vocabulary.' It does not name alternatives or when-not-to-use, but the context is clear enough to route an agent correctly. The sibling list provides obvious contrast with list_key_terms, so a 4 is appropriate.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral specifics: it is limited to one subject, includes remaining MCP previews, does not return billing details, and does not change access. These details reinforce the annotations and give the agent a clearer picture of side effects and limits.

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 tight sentences with no filler. The first states the core function, and the second adds valuable negative guarantees. Every clause earns its place, and the key scope limitation 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?

With an output schema present, return-value details are covered elsewhere. For a small read-only tool with one parameter, the description adequately covers purpose, scope, and exclusions. The main gap is the weak documentation of subjectSlug, but that was already penalized under parameter semantics.

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 the single subjectSlug parameter. It only loosely indicates 'one subject' without explaining what a subjectSlug is, where to obtain one, or what format it should take. The parameter name is somewhat self-explanatory, but the description does not provide enough semantic detail for an agent unfamiliar with the domain.

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 names a specific verb ('Explains') and resource ('which features this account can use for one subject and its remaining MCP previews'), and pairs it with clear exclusions: no billing information and no access changes. It distinguishes the tool from the many get_my_* siblings by focusing on account entitlements and previews rather than progress or history.

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 conveys the tool's scope—used to check per-subject feature access and MCP previews—and explicitly states that billing information is not returned and access is not changed. However, it provides no explicit 'when to use vs. alternatives' guidance or mention of sibling tools, so an agent must infer when this is the right get_my_* choice.

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 safety profile is covered. The description adds valuable behavioral context about including graded scores and recent weak areas, which goes beyond the schema. 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?

Two sentences with no filler. The first sentence front-loads the return value; the second sentence gives the use case. 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 two-parameter read-only tool with a rich output schema and clear annotations, the description covers purpose, return content, and use case. It could slightly improve by explicitly contrasting with get_frq_attempt_history, but this is a minor gap given the already distinct wording.

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 input schema fully documents both subjectSlug and intent, including enum values. The description only indirectly reinforces 'for one subject' and does not add new meaning to the parameters beyond what the schema provides.

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 returns the signed-in student's saved free-response attempts for one subject, including scores and recent scoring-point weak areas. This specific verb+resource combination distinguishes it from the many sibling getters such as get_frq_attempt_history and get_my_practice_history.

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 use case: 'Use it to see what a student has already practiced and where they are losing points before recommending what to work on next.' This gives clear contextual guidance, though it does not explicitly name alternatives or when not 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?

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing pagination ('bounded page'), the effect of practice resets ('Honors practice resets'), and side-effect behavior ('Does not save, score, or consume a content preview'). This gives an agent a clear model of what happens during the call.

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: the first sentence states the core action and resource, and the following two sentences add essential behavioral caveats. Every sentence earns its place with 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?

For a read-only, paginated history tool with a rich output schema and safety annotations, the description covers purpose, pagination, reset behavior, and side-effect exclusions. The main gap is the lack of parameter-level clarification, especially for the required subjectSlug, but the schema and self-evident naming partially cover this.

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 only vaguely hints at pagination via 'bounded page'. It does not explain subjectSlug, cursor, or limit semantics, and no parameter names appear in the description. The agent must infer most parameter meaning from the schema 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 states the verb ('Reads') and the resource ('bounded page of your saved self-study MCQ answers with current question explanations'). It differentiates from siblings by emphasizing read-only retrieval of saved answers and noting it does not save or score, which separates it from check_practice_answer and submit_practice_answer.

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 intended use case, reviewing past self-study MCQ answers, is implied by the title and first sentence, but no explicit alternative or when-not-to-use guidance is given. The statement 'Does not save, score, or consume a content preview' clarifies exclusions but does not name sibling tools or conditions for choosing this one.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: progress is 'durable' but 'respecting the website progress reset,' and assignment/study-plan summaries are only included 'when their separate permissions are granted.'

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?

Three sentences, each earning its place: core return data, permission-gated additions, and a clear usage directive. No filler 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?

With an output schema present, return-value details are not the description's job. It covers what the progress includes, durability/reset behavior, permission dependencies, and when to call it, which is complete for a read-only progress 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 100%, so the schema fully documents subjectSlug and intent. The description reinforces the 'one subject' scope and mentions permission-gated summaries, but adds little semantic value beyond the schema's own parameter 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?

States a specific verb ('Returns') and resource ('the signed-in student's durable Fiveable progress for one subject') plus the exact data included. It is clearly distinguished from siblings like get_my_practice_history and get_my_frq_progress by focusing on the aggregate progress for one subject.

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 says 'Call this before choosing what to explain or practice so recommendations carry across conversations and AI clients.' It gives clear when-to-use guidance, but does not name alternatives or explicitly say 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses non-obvious operational behavior: a returned set consumes one full-content preview unless existing access covers practice, and roughly 300 tokens per question (more with images). It also explains the adaptive drop-to-easier-type behavior driven by recentCorrect/recentAnswered.

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?

Purpose is front-loaded and most sentences carry unique value (topic matching, stimulus sets, cost, quota). It is longer than strictly necessary for a 13-param tool, and paragraph two drifts into answer-submission plumbing better owned by sibling tools, but there is little pure 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?

Output schema exists so return values need not be described, and for a 13-parameter, 5-enum tool the description still covers scope selection, tier mechanics, image/stimulus behavior, quota consumption and cost. 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: free-text topics are matched against Fiveable's course map (natural phrasing works), tier semantics are explained in behavioral terms, and the recentCorrect/recentAnswered pairing with a 3+ answer threshold is clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb+resource (returns course-specific multiple-choice practice questions) and explicitly positions itself as 'targeted or mixed practice, distinct from Fiveable's durable adaptive diagnostic', so an agent can separate it from start_diagnostic without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use rules: omit topic for whole-subject mixed practice, use unitId for broad unit practice and not a topic id as a proxy, pass tier with recentCorrect/recentAnswered for tier adjustment, and set includeAnswers true only when the student asks. It also names the routing alternatives (adaptive diagnostic, check_practice_answer, submit_practice_answer, get_subject_outline).

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, so the safety profile is known. The description adds value by clarifying that the tool never starts or retries scoring, and by indicating that the response can be either a status or a saved result, which helps set expectations about partial vs. final outcomes.

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 short sentences with no filler. The core action is front-loaded, and the clarifying side-effect boundary is stated immediately after, making the description easy to parse and act on.

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 retrieval tool with annotations covering safety and an output schema covering return values, the description is complete. It states what the tool reads, implies the ID-based lookup, and explicitly rules out write actions. 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 description does not explain the parameters, and schema description coverage is only 50% because scoringJobId lacks a description. However, the parameter name is self-explanatory and the pattern provides structural validation, while intent has its own schema description. The description adds no semantic value beyond what the schema already provides.

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 ('Read') and a specific resource ('status or saved result of your FRQ scoring request'), making the tool's function immediately clear. It also distinguishes itself from scoring initiation tools by stating it never starts or retries scoring.

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 conveys that this tool is for retrieving an existing scoring request's status or saved result, and explicitly rules out using it to start or retry scoring. It does not name the alternative tool for starting a scoring request, but the context is clear enough for an agent to make the right call.

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 readOnly/idempotent annotations, the description reveals that an in-progress plan reports pending with a retry delay and that task ids are stable. This adds meaningful behavioral context about polling and revision handling that the annotations do not convey.

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?

Three sentences with dense, relevant information and no filler. The core read action is front-loaded, followed by lifecycle guidance and the non-mutating guarantee.

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?

With an output schema present, annotations covering safety, and one simple parameter, the description covers all operational essentials: what the plan contains, the pending state, polling guidance, and revision usage. Nothing needed for correct invocation 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 0%, so the description must compensate for the single planId parameter. It adds that the plan must be owned and that the tool should be polled after create_study_plan, which implies where the ID comes from. The schema pattern provides format, and the description provides enough operational semantics for one 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 uses a specific verb ('Reads') and a specific resource ('one owned study plan'), and lists the key contents ('stable task ids, completion state and revision'). This clearly distinguishes it from list_my_study_plans and create_study_plan.

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 tells agents to poll this tool after create_study_plan instead of creating again, and to use the returned revision for task changes. It also clarifies that reading older plans never changes them, giving both 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: the tool returns a complete outline with study guide slugs and gives a token-cost estimate. 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?

Three front-loaded sentences, each earning its place: what it returns, how it is used, and cost considerations. No filler or repetition of schema fields.

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 rich annotations and presence of an output schema, the description is sufficiently complete for selecting and invoking the tool. It covers scope, purpose, and cost. It could have explicitly contrasted itself with get_unit_overview, but the schema already provides subject resolution guidance, so nothing critical 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%, so the schema already documents both intent and subjectSlug, including examples and the suggestion to use list_subjects. The description adds no parameter-specific semantics, but the baseline of 3 is appropriate because the schema carries the full 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 names a specific action (returns the full unit and topic outline) and a resource (one AP subject), and distinguishes it from siblings like get_unit_overview and get_study_guide by emphasizing the complete course map and study guide slugs. It is clear what this tool produces and how it differs from adjacent 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 implies clear usage context: use it for study planning and to locate individual study guide slugs before retrieving guides. It does not explicitly name alternatives or exclusions, but the stated use cases are specific enough to route an agent appropriately among the sibling 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, idempotentHint, and non-destructive behavior. The description adds valuable cost information ('Moderate cost — roughly 1-3k tokens'), which goes beyond the structured annotations. No contradictions found.

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 core purpose is front-loaded, followed by a concise use-case and cost note. 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?

For a read-only, idempotent tool with a rich input schema and output schema, the description fully covers purpose, content of the return value, use context, and cost. Nothing essential is missing for an agent to decide whether to call it.

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 schema already documents all parameters well, including examples and resolution behavior. The description does not need to add parameter semantics and doesn't, which is acceptable at the baseline.

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: 'Returns the overview page for one unit of an AP course.' It clearly enumerates what the overview contains (coverage, exam weighting, topics, study plan), making it distinguishable from sibling tools like get_subject_outline or get_study_plan.

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 phrase 'Suitable when a student is reviewing a whole unit' provides clear context for when to invoke this tool. It does not explicitly name alternatives or exclusions, stopping 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 signal readOnlyHint, openWorldHint=false, idempotentHint, and non-destructive behavior, so the description's extra context is a bonus. It adds useful behavioral nuance by noting that academic year is included 'when known', mentioning readable-artifact readiness, and explicitly scoping out user-generated content. There is 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 two sentences with no filler. The core purpose is front-loaded, and the second sentence earns its place by drawing a clear boundary around what the tool does not return.

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?

With a rich output schema, safety-revealing annotations, and a clear scope statement, the description is largely adequate for a read-only listing tool. The main missing piece is explicit guidance on when to choose this tool over get_cheatsheet or search_content, but the schema and annotations carry much of the remaining context.

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 bears the burden of explaining the five parameters, but it does not explain limit, cursor, unitNumber, subjectSlug, or courseVariant directly. The phrase 'course and unit PDFs' weakly maps to subjectSlug and unitNumber, and 'course variants' hints at courseVariant, but limit and cursor remain entirely unaddressed.

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 ('Find') and a specific resource ('approved Fiveable course and unit PDFs'), and enriches it with concrete details about course variants, academic year, source links, and artifact readiness. It also explicitly excludes user galleries and personal visuals, which helps distinguish it from broader content-listing 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 a clear scope and one meaningful exclusion, but it does not name alternative tools or specify when to use this list tool versus fetch tools like get_cheatsheet or search_content. The intended usage is mostly implied by the word 'approved' and the list-oriented verb, rather than explicitly contrasted with 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 carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond those: stable ID ordering for pagination ('unchanged filters continue pagination'), a return-format disclosure ('prompt ids and summaries rather than full prompts'), and a cost signal ('Cheap'). These enrich the agent's model of side effects and behavior without contradicting 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?

Four compact sentences, each earning its place: purpose+filters, pagination behavior, return format, and cost. The core purpose is front-loaded before behavioral details. The standalone 'Cheap.' sentence is a slightly informal touch but adds real signal; overall minimal waste.

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 (covering return structure), 8 parameters, and rich annotations, the description covers the essentials: what is listed, how filtering works, pagination stability, and cost. The privacy aspect of intent is left to the schema description, but the description is still adequate for correct invocation without major gaps.

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 75%, so most parameters (limit, intent, unitId, frqType, subjectSlug, courseVariant) already have descriptions. The tool description adds value for the undocumented excludeIds by mentioning 'excluded IDs' and contextualizes cursor via the pagination statement. It does not, however, elaborate on parameter formats or valid values, so it compensates only partially for the 25% coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource pair ('List free-response practice prompts for an AP subject') and names the filter dimensions (FRQ type, unit, excluded IDs). It clearly distinguishes itself from siblings such as get_frq (single prompt) by framing this as a listing operation, and from list_practice_questions by scoping to FRQs. No ambiguity about what the tool does.

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 through 'Returns prompt ids and summaries rather than full prompts,' which hints that get_frq is the alternative for full-prompt needs, and 'optionally filtered' signals a discovery-style listing. However, it never explicitly names the sibling or states a when-not-to-use condition, so the routing guidance is implied rather than 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?

The annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe to call repeatedly. The description adds that results are paginated alphabetically, include stable slugs, and are 'cheap' (which suggests low cost or resource usage). It does not mention rate limits or any other behavioral traits beyond the annotations, so it's strong but just shy of perfect.

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: it states the main purpose, use cases, and key features (slugs, cheap) in two sentences. Every clause contributes meaning, with no redundant or generic phrasing.

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 straightforward list tool, and the description plus schema cover all necessary information for a user to call it: the purpose, parameters, and behavior are clearly defined. The only minor gap is that the description doesn't explain what a 'term slug' is or how to use it, but playful hint is given (for full definitions use get_key_term). The output schema exists, so the return format does not need to be described. Overall, it is highly complete for the tool's complexity.

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%, meaning all 5 parameters are described in the input schema. The description adds value by mentioning 'stable term slugs' which hints at the subjectSlug parameter, but it doesn't explain any parameter in depth beyond what the schema already provides. Since the schema fully documents each parameter, 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 clearly states the tool lists key vocabulary terms for an AP subject, with alphabetical pagination. It distinguishes itself from get_key_term (singular term vs. list) and list_subjects (which finds subjects), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states suitable use cases: 'building flashcards or checking what vocabulary a student should know.' It also mentions cost ('Cheap'), which implies it is appropriate for frequent listing. While it doesn't name alternatives, the clear use cases and the existence of get_key_term for individual terms make when to use this tool apparent.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: only released scores are included, teacher rosters and answer keys are not exposed, and completing work is not possible through this tool. This clarifies limits beyond the structured 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 with no filler: purpose, included data, exclusions, and a limitation are all stated efficiently. The main behavior is front-loaded, and every sentence contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Annotations and output schema cover safety and return structure, and the description supplies necessary scope and caveats. The only notable gap is the absence of any explanation for cursor/subjectSlug filtering behavior, which an agent may need when calling the tool with more than the default simple 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% and the description does not explain any of the parameters (limit, cursor, subjectSlug). While limit and subjectSlug are somewhat self-explanatory from their names and constraints, the cursor's role in pagination is left entirely implicit. The description does not compensate for the missing schema-level parameter explanations.

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 ('Lists') and clearly identifies the resource: assignments delivered to the connected student's enrolled classes, signed-in submissions, and claimed guest work. It also states what data is included and explicitly excludes teacher rosters and answer keys, making it easy to distinguish from 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 provides clear context about what the tool returns and for whom, which implies when it should be used. It does not explicitly name alternative tools or say 'use X instead', but the scope is well-defined and the exclusions help disambiguate it from related functionality.

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 readOnly/idempotent/destructive annotations, the description discloses meaningful behaviors: pagination, deduplication of retried submissions, honoring the website progress reset, and the fact that unit tests never show an AP projection. It also explicitly excludes reading browser-only or active exam state. No contradiction with annotations 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?

Three tight sentences deliver scope, behavioral caveats, and exclusions without filler. The main function is front-loaded, and every clause earns its place. This is an efficient, well-structured description.

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 output schema and annotations cover safety and return shape, so the description does not need to restate those. It adds strong behavioral context, including deduplication, pagination, and exclusions. The only notable gap is the absence of any parameter-level guidance, especially for the optional subjectSlug filter.

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 needed to explain limit, cursor, and subjectSlug, but it does not. The only indirect hint is 'paginates,' which relates to cursor usage but adds no real parameter-level meaning. The agent must rely entirely on the schema 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 opens with the specific verb 'Lists' and narrows the resource to 'the connected student's completed full-length and unit-exam results.' This clearly distinguishes it from exam-level tools like get_exam_results and practice-history tools. The scope is precise and immediately actionable.

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 clear usage context: it lists completed exams for the connected student, honors progress resets, and deduplicates retried submissions. It also states what it does not cover, such as browser-only or active exam state. It stops short of explicitly naming sibling alternatives or giving when-to-use versus when-not-to-use guidance, so it misses 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: the tool returns canonical slugs and feature flags, and is cheap at roughly 1-2k tokens. 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?

Three sentences, zero filler. The main function is front-loaded, the useful output details are included, and the cost note is a relevant operational detail for an agent deciding whether to call the 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 read-only listing tool with two optional params, full schema coverage, and an output schema, this description is complete. It explains purpose, output contents, when to use it, and cost without missing anything an agent needs to 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 schema fully documents both parameters, including the intent enum and the optional search filter. The description doesn't add parameter-level details, which is acceptable given the schema already handles that 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 states a specific verb and resource: lists every AP subject Fiveable covers, and specifies the output includes canonical slugs and feature flags. This clearly distinguishes it from sibling list tools like list_cheatsheets or list_key_terms.

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 it is suitable when a subject slug is not already known, giving clear context for when to invoke it. It does not name alternative tools or spell out when not to use it, 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 readOnlyHint, idempotentHint and destructiveHint=false. The description adds real context beyond that: it opens an interactive UI panel, connected accounts persist answers to Fiveable progress, and anonymous sessions are unsaved previews. That persistence distinction is genuinely useful.

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?

Four short sentences, front-loaded with what the tool opens before the account-persistence caveat. No wasted phrasing, though the second sentence is somewhat redundant with the first.

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 values need not be explained, and annotations cover the safety profile. However, with 9 parameters and 33% schema coverage, the description leaves most invocation semantics undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% across 9 parameters, so the description must compensate and does not. It never mentions subjectSlug, limit, questionFormat, tier, unitId or topicId semantics, even though several of these are required or constrained (limit max 20, questionFormat default auto).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Opens') and resource ('interactive multiple-choice practice panel') with detail about the question/answer/explanation components. This distinguishes it from data-fetching siblings like get_practice_questions, though it never names an alternative explicitly.

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?

Implies usage ('Students select answers directly in the panel') and notes connected vs anonymous practice, but gives no explicit when-to-use guidance relative to get_practice_questions, start_diagnostic, or submit_practice_answer. The routing decision is left to inference.

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 write semantics and openWorldHint, but the description adds real context beyond them: support may follow up, only the reported issue is transmitted (no conversation history or PII), Fiveable resolves content and reporter identity, and matching requestId retries are idempotent. It repeats the idempotentHint already in annotations, so it falls short of fully additive disclosure, but the data-handling and follow-up behavior are genuinely new information.

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?

Four short sentences, front-loaded with purpose and approval requirement, and each sentence carries distinct information (gating, scope of payload, resolution ownership, idempotency). Slightly dense/packed, but no 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 destructive-capable write tool with an output schema present, the description covers the confirmation gate, payload scope, privacy handling, and retry semantics, which is most of what an agent needs. It does not say what happens on failure or how support follow-up is surfaced, but the output schema can carry that.

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 60%, so the description must carry some weight, and it does: it constrains 'description' to the issue only (excluding transcripts and unrelated personal notes) and clarifies 'confirmReport' as gated on an explicit student request. It also notes idempotency keyed on requestId. contentType and contentId semantics are left to the 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?

States a specific verb and resource ('Submits a caller-requested content issue to Fiveable support') with a clear destination. No sibling tool in the list does anything comparable, so an agent can route to it unambiguously. The purpose is stated in the first clause without requiring the title.

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 hard precondition ('Requires explicit confirmReport approval') and scopes intake to caller-requested issues, which implies when the tool may be used. However, it does not contrast with any alternative action (e.g., answering the student directly or searching content first), so usage guidance is implied rather than 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?

Annotations only indicate readOnlyHint false, idempotentHint true, etc. The description adds substantial behavior: requires sign-in, one free preview, saves attempt to progress, returns a pending job, and mandates polling. No contradiction with annotations; these are valuable beyond what annotations convey.

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 well-structured, front-loading the core purpose before covering photo handling, scoring rubric, auth, polling, and retries. Every sentence adds necessary context, though it is slightly longer than necessary for a simple 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 complex tool with 10 parameters and a required workflow, the description covers all critical operational aspects: external FRQ handling, image transcription, authentication, output as a pending job, polling, and retry semantics. With an output schema present, the return format is already defined, so 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?

Schema description coverage is 90%, so most parameters are already documented. The description adds minimal new meaning—mainly that promptImages preserve graphs/artwork, and reiterates the transcription confirmation workflow already in the schema. It does not significantly compensate for the remaining 10%.

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 scores a student's existing FRQ even when it did not come from Fiveable, using a specific verb and resource. It explicitly differentiates from the sibling tool score_frq_response by scoping to external FRQs, making the purpose 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?

Provides explicit usage guidance: use this when the FRQ is external, and includes a detailed workflow for handling photos (transcribe, confirm, then call). It also instructs to poll get_scoring_result and reuse requestId for retries, covering when and how to use it effectively.

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 safety. The description adds useful behavioral context beyond those: it returns only 'titles and canonical references rather than full content' and notes that the search is cheap. This helps an agent set expectations about cost and output shape.

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?

Three short sentences, no filler. The main action and scope come first, followed by the use case and a key return-value caveat. 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 presence of a full output schema, rich annotations, and a 100%-covered input schema, the description provides the missing context: the cross-cutting search scope, when to prefer it, and the lightweight return format. Nothing essential is left for the agent to infer.

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 each parameter is already documented. The description adds general keyword-search framing, but it does not add meaning beyond the schema for query, limit, intent, or subjectSlug. Baseline 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 opens with a specific verb and resource: 'Keyword search across every Fiveable study guide, unit, subject hub and key term.' This clearly identifies the tool's scope and distinguishes it from sibling get_ and list_ tools that operate on specific known resources.

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 guidance about when to use the tool: 'Suitable when the relevant subject or guide is not known.' It implies the alternative is to use more targeted tools when a known resource exists, though it does not name those alternatives explicitly.

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 readOnlyHint=false and idempotentHint=true already in annotations, the description adds valuable behavioral context: it 'creates durable diagnostic progress' and returns one adaptive question at a time. These are non-obvious side effects and interaction semantics that go beyond the annotations, with no contradiction.

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?

Three short sentences, each earning its place: the first states the action, the second handles the unitId conditional, and the third covers return behavior and side effect. There is no filler or repetition of details already present in the schema.

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 stateful creation tool with an output schema and an idempotency annotation, the description covers the core flow, state creation, and unit scoping. It does not spell out how to submit answers or what subjectSlug values look like, but these are reasonably inferable from context and 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?

The description explains the key unitId behavior—whole-course vs unit-scoped—which the schema leaves undocumented. However, it adds nothing about the required subjectSlug and relies on schema descriptions for intent, requestId, and courseVariant. With 60% schema coverage, this is partial but non-trivial compensation.

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, 'Starts Fiveable's canonical adaptive diagnostic', and the return/side-effect clause distinguishes it from siblings like get_diagnostic_results and submit_diagnostic_answer. The unitId scoping sentence adds precision about the resource scope, making the tool's purpose 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 gives clear conditional guidance: omit unitId for full-course coverage or provide an exact unitId to scope to a unit. It also implies the start of an interactive flow by noting it returns one question at a time. It does not explicitly name sibling alternatives, but 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=false, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context: it saves one answer, returns feedback plus exactly one next adaptive question, and accepts multiple answer formats. It does not contradict annotations. It could add more about side effects (e.g., whether the answer is permanently recorded or whether the diagnostic advances), but the idempotency hint and the explicit 'saves' verb cover the core 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?

Three sentences, each carrying distinct information: what it does, what inputs it accepts, and the per-call constraint. No filler or repetition of schema details. The most important behavioral fact (saves one answer, returns feedback + next question) 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?

The tool has an output schema, so return values need not be described. The description covers the core call semantics, accepted answer formats, and the one-question limit. It doesn't mention retry behavior (requestId) or the intent parameter's role, but those are documented in the schema. For a mutation-like tool with idempotency hints, this is reasonably 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 only 40%, so the description must compensate. It does: it explains that 'answer' can be an option letter, full text, or answer id, and that the tool handles one question per call. It also clarifies the 'intent' parameter's purpose indirectly by saying 'privacy-safe reason' in the schema, but the description itself doesn't elaborate on requestId or sessionToken. Still, the description adds meaningful meaning beyond the schema for the key 'answer' 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 a specific verb ('Saves'), a specific resource ('one answer in the connected student's active Fiveable diagnostic'), and the exact outcome ('returns feedback plus exactly one next adaptive question'). It also clarifies the accepted input forms and the one-question-per-call constraint, which distinguishes it from sibling tools like submit_practice_answer and check_practice_answer.

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 implies when to use it: when the agent has an active diagnostic question and needs to submit an answer. It explicitly says 'Handles one question per call,' which is a usage constraint. However, it does not explicitly name alternatives or state when not to use it (e.g., use submit_practice_answer for practice questions, not diagnostics).

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 indicate idempotentHint=true and readOnlyHint=false, so the agent knows it's a mutating but idempotent operation. The description adds that it records progress and returns correctness/explanation, but doesn't explicitly mention that retries with the same requestId will not create duplicates, which is a key behavioral nuance for idempotency. However, the annotations cover the core, and the description adds useful context about the return value.

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, focused sentence that front-loads the action and outcome. It mentions the key parameters (question id) and the return value, but could be slightly more concise by avoiding redundancy with the title. Still, it's tight and structured well.

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 presence of an output schema (not shown but indicated) and comprehensive parameter descriptions, the description covers the essential purpose and expected result. It could mention idempotency behavior or references to check_practice_answer, but these are minor omissions given the schema richness. The tool is moderately complex with 4 params, but the description is adequate 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?

The input schema already documents all 4 parameters with descriptions (100% coverage). The description adds minimal extra context beyond the schema, such as the intent field's purpose for privacy, which is already in the schema. It doesn't add new semantics, so a baseline 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 clearly states the action (records the signed-in student's answer), the resource (a multiple-choice practice question), and the outcome (counts toward progress, returns correctness and explanation). It also distinguishes itself from check_practice_answer, which likely just checks an answer without recording, making the purpose 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 implies it should be used when a student answers a practice question from get_practice_questions and wants it recorded for progress. It doesn't explicitly state when not to use it (e.g., for checking without recording), but the sibling tool check_practice_answer suggests an alternative. Clear context but no explicit exclusions.

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 idempotentHint=true and readOnlyHint=false. The description adds 'self-reported planning' and 'retry identical input safely', which align with idempotency and provide context beyond the annotations. It does not contradict annotations, and the added context is valuable.

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 central action and key constraints are front-loaded, and every phrase 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 covers purpose, usage exclusions, and key parameter semantics. With an output schema and annotations handling safety and idempotency, it is sufficiently complete. It doesn't mention error handling or prerequisites, but those are not essential given the other structured fields.

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 only 25% (only requestId has a description). The description adds meaning to expectedRevision ('Supply the latest revision') and reinforces requestId's uniqueness, but it does not explicitly describe tasks or planId. These are inferable from names and schema patterns, but the description could compensate more given the low 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 clearly states a specific verb (marks) and resource (owned plan tasks) and explicitly differentiates from quiz/practice submissions. This distinguishes it from sibling tools that handle scoring. The phrase 'at the student's request' adds context without ambiguity.

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 when-not ('never a quiz score or practice submission') and a when ('at the student's request'), but does not name alternatives or explicitly say when to prefer this tool over others. With no direct update sibling, the lack of alternatives is acceptable, but the guidance is partial.

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