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?

The description discloses the async build behavior ('Returns a plan id immediately while the plan builds'), the retry semantics via requestId, and the idempotency caveat ('never call this twice'). These add value beyond the annotations (idempotentHint, openWorldHint) and do not contradict 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?

Four concise, front-loaded sentences that pack in purpose, prerequisites, async behavior, retry guidance, and a pointer to the read tool. Every sentence earns its place with no 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?

For a tool with 5 parameters and an output schema, the description covers the key operational aspects: when to use it (signed-in), what it returns, how to read the result, and how to retry safely. The output schema presumably details the plan structure, so the description is sufficiently 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 coverage is only 20% (only requestId has a description). The description mentions 'topic and available time' which loosely maps to scope and timeAmount/timeUnit, but it does not explain subjectSlug or clarify the format of scope beyond a hint. It adds some meaning but does not compensate for the low schema coverage.

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

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

The description clearly states a specific verb ('Creates and saves') and resource ('trackable Fiveable study plan') and distinguishes it from the sibling get_study_plan by explaining the immediate return and async build. It is unambiguous 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?

Provides explicit guidance: 'Free for signed-in students' sets a prerequisite, 'Reuse requestId with identical input to retry; never call this twice for the same plan' gives concrete usage rules, and it points to get_study_plan for reading the result. This is strong, actionable direction.

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?

Beyond the readOnly and idempotent annotations, the description discloses important behaviors: it reads only bounded pages, returns actual page images, does not transcribe image-only pages, and never starts processing. This gives an agent a realistic model of what to expect and what limitations exist.

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 concise sentences with no filler. The key behavior, output contents, limitation, and fallback guidance are all packed efficiently, with the core action 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 description is largely complete given the output schema and annotations: it covers scope, safety, page boundaries, image behavior, and a fallback path. The only notable gap is parameter acquisition — specifically how to know the cheatsheetId — but list_cheatsheets likely covers that elsewhere.

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

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

Schema description coverage is 0%, so the description carries the burden of parameter meaning, but it does not explain cheatsheetId, page, or limit explicitly. 'Bounded pages' hints at the page and limit parameters, but the agent is left to infer how they work and how to obtain cheatsheetId.

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 ('Read') and resource ('official Fiveable PDF' cheatsheet), and adds what the result includes: page citations, extracted text, and images. It distinguishes this read-based tool from listing or scoring siblings by emphasizing 'bounded pages' and 'prepared official' content.

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

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

The description gives explicit guidance for the fallback case ('If artifacts are unavailable, use the approved PDF link') and notes that this tool never starts processing, signaling a safe read. It does not explicitly name sibling tools or state when to prefer this over list_cheatsheets or get_study_guide, but the intended context is reasonably 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds a material behavioral trait: 'One call consumes one full-content preview for a free caller.' This quota/cost disclosure goes beyond the structured annotations and is highly relevant for an agent deciding whether to call 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?

Three short sentences, each earning its place: the result statement, the usage guidance, and the quota warning. The most important selection guidance is front-loaded before the cost caveat, with no redundant filler.

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

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

The combination of description, annotations, and output schema gives an agent everything needed to select and invoke the tool: what it returns, when to use it, and one critical quota limit. The schema handles parameter and return-shape details, so the description does not need to repeat them.

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 67%, and the schema already documents query, intent, guideSlug, and subjectSlug. The description adds only light semantic context such as 'one question' and 'small set', while maximumTokens remains undocumented in both the schema and the description. A 3 reflects a balanced, minimally adequate contribution.

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

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

The description uses a specific verb ('Returns') and resource ('passages from Fiveable study guides') with a selection criterion ('most relevant to one question'). It clearly differentiates from fetching a full guide, so an agent can distinguish it from get_study_guide 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?

It states explicit use cases: narrow explanations, research questions, and checking student notes. It also gives a direct alternative comparison by saying 'instead of fetching a full guide', which tells the agent when not to use the broader guide-fetching 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 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?

Annotations already mark readOnly and idempotent, so the description's added detail about topic matching, source-based stimulus sets, viewable images, and consumption of one full-content preview is genuinely additive. It also discloses token cost and adaptive tier-dropping behavior, which an agent needs to predict side effects. No statement contradicts the annotations.

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

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

The description is long but organized: core behavior first, then source-set nuance, then progress/adaptive behavior, then cost. Every sentence adds information not present in the schema (token cost, preview consumption, image rendering). A little redundancy around 'targeted or mixed practice' is minor.

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 12-parameter tool with an output schema, the description covers selection behavior, scoping, adaptive inputs, access/cost side effects, and answer submission integration. Missing items like exact return shape are handled by the output schema, so the description is effectively 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 covers 100% of properties, so baseline is 3, and the description adds real value on top: natural-language topic matching, tier/recentCorrect/recentAnswered behavior for dropping difficulty, and auto mode selecting exam when no topic is given. It also clarifies limit includes questions in a stimulus set, which is not obvious from the schema alone. This pushes above 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?

Description opens with 'Returns original, course-specific multiple-choice practice questions' — a specific verb and resource. It further clarifies what the tool is not ('distinct from Fiveable's durable adaptive diagnostic'), and the schema's mode/topic params reinforce targeted vs mixed practice. This separates it from siblings like get_diagnostic_results and get_frq.

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 tells the agent when to omit topic for whole-subject mixed practice and when topic drilling applies, and explicitly distances the tool from the adaptive diagnostic. It also routes answer checking to check_practice_answer or submit_practice_answer, though it doesn't name the diagnostic sibling as an alternative. That's clear use-context with a partial exclusion, not exhaustive when/when-not.

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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it consumes one full-content preview for free callers unless access exists, and it warns that a full guide is expensive at 3-8k tokens. This significantly helps an agent anticipate cost and access side effects.

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

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

The description is compact and front-loaded with the core behavior, followed by suitability and cost context. Every sentence contributes useful information, though it is slightly longer than strictly necessary.

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 input schema, annotations, and an output schema present, the description covers the important non-obvious context: Markdown output, access/preview consumption, token cost, and when to use the tool. It is complete enough for an agent to invoke this tool appropriately.

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 baseline is 3. The description adds only marginal semantic value over the schema, such as noting that guideSlug accepts a close approximation of a title, but the schema already documents canonical references and title matching.

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 and resource: it returns the full text of one Fiveable AP study guide as Markdown. It effectively differentiates this tool from siblings like get_frq or get_cheatsheet by emphasizing 'full text' and 'Markdown', though it does not explicitly name a sibling alternative.

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 a student asks to learn or review a topic. It does not state exclusions or name alternatives like get_cheatsheet for concise review, so it falls just short of full 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?

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?

The annotations already provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral detail beyond those: stable ID ordering, pagination continuity with unchanged filters, truncated return content, and a performance hint ('Cheap'). No statement contradicts 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?

Three short sentences cover the core operation, filter options, pagination behavior, return shape, and cost profile. Every sentence contributes distinct information and the most important action is front-loaded. There is no filler or repetition of 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 read-only list tool, the description is complete: it states the resource, optional filters, pagination stability, and that results are summaries rather than full prompts. An output schema exists, so return-value detail is not required here; an agent has enough guidance to select and invoke the tool correctly.

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

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

With 71% schema coverage, the description compensates by tying frqType, unitId, and excludeIds to the stated filter behavior and by clarifying pagination semantics through 'unchanged filters continue pagination.' It does not fully elaborate on cursor mechanics, but the schema and the pagination statement provide enough operational meaning.

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 ('Lists') and a specific resource ('Fiveable's free-response (FRQ) practice prompts for an AP subject'), and names the optional filter dimensions. This clearly distinguishes it from siblings like get_frq (single prompt retrieval) and other list tools, while also signaling it returns a filtered collection rather than full prompt bodies.

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 call this tool: to list FRQ practice prompts for a subject, with optional filters, pagination, and a lightweight result. It does not explicitly name alternatives such as get_frq for full prompt content, but 'Returns prompt ids and summaries rather than full prompts' and 'Cheap' imply the appropriate usage boundaries.

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 readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: eligibility, cost, performance characteristics ('Cheap'), and pagination behavior. It does not contradict the annotations.

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

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

Three short sentences that front-load the core purpose and scope. Every sentence adds meaningful information without repeating annotations or 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?

For a simple read-only list operation with a full output schema and strong annotations, the description is nearly complete: it covers audience, eligibility, cost, and pagination. The only notable gap is undocumented subjectSlug filtering, but the parameter name is self-explanatory.

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 compensate by explaining limit, cursor, and subjectSlug. It only hints at pagination with 'paginated', leaving cursor mechanics and the subject-filtering semantics largely to inference from parameter names.

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 ('Lists') and resource ('connected student's saved Fiveable study plans'), and clarifies scope with 'including website plans'. This clearly distinguishes it from siblings like get_study_plan and create_study_plan without requiring schema inspection.

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 relevant context for when it is appropriate: signed-in students, free, cheap, paginated. However, it does not explicitly say when to prefer this over alternatives, such as using get_study_plan for a single plan or list_my_assignments for assignments.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavioral context beyond those: the report may lead to normal support follow-up, Fiveable resolves content and reporter identity, and requestId should be reused on retries. It also sets privacy boundaries about what should not be submitted.

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

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

The description is four sentences with no filler. It front-loads the primary condition, then adds necessary exclusions, follow-up context, and idempotency guidance. Every sentence earns its place.

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

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

Given the output schema exists and annotations cover safety and idempotency, the description is complete enough for an agent to invoke the tool correctly. It covers when to use it, what not to include, what happens after submission, and how to handle retries.

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 does not carry the full burden, but it adds value beyond the schema. It clarifies requestId semantics with 'Reuse requestId on retries,' reinforces the description parameter's scope ('Only the issue the student wants reported'), and ties confirmReport to the explicit-student-request condition. It does not add much for contentId or contentType, but those are already well-defined in 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: 'Submit a content issue to Fiveable support.' It clearly identifies the tool's purpose and distinguishes it from the read-oriented sibling tools by framing it as a support/report action, not a content retrieval or scoring operation.

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

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

The description explicitly states when to use the tool: 'only when the student explicitly asks to report it.' It also gives clear exclusions: do not automatically report disagreements, and do not send conversation history, unrelated notes, or personal information. This is strong usage guidance with no ambiguity.

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?

The description adds meaningful behavioral detail beyond the annotations: scoring is saved and asynchronous, a scoring job id is returned for status retrieval, requestId enables idempotent retries, and one free score is available to signed-in students. It aligns with the annotations (readOnlyHint=false, idempotentHint=true) and does not contradict 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?

Four dense, front-loaded sentences deliver the core purpose, supported input types, exclusions, return behavior, idempotency, and access constraint without redundancy. No sentence is wasted, and the most important scoping information appears 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?

Given the tool's complexity (9 parameters, nested objects, output schema) and the low schema coverage, the description covers the main behavioral contract well: what to submit, what to expect back, and retry semantics. It does not explain how to choose between businessProjectPracticeMode values or why promptVariantId is constrained, so it is slightly incomplete for the full optional surface.

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 22%, so the description needs to compensate, and it does by enumerating supported content types (text, subparts, drawings/photos, LEQ selection, CSP program code, Business project references) and explaining the purpose of requestId. However, it does not add semantics for intent, promptVariantId, or businessProjectPracticeMode, so some optional parameters remain underspecified.

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 pairs a specific verb ('Submits') with a precise resource ('student's own response to a Fiveable practice FRQ') and characterizes the operation as saved and asynchronous. It explicitly excludes teacher assignments and exams, which helps distinguish it from scoring-related siblings. The scope and exclusions make 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 clearly states when to use the tool (student's own practice FRQ responses, including text, drawings, LEQ, CSP, and business projects) and gives an explicit exclusion (teacher assignments and exams). It provides clear context, but does not name which sibling tool to use instead for excluded cases, so it stops short of fully explicit alternative routing.

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?

Annotations already indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that it 'creates durable diagnostic progress' and 'returns one adaptive question at a time', which are behavioral traits beyond the annotations. No contradiction exists.

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

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

Three sentences, front-loaded with the core purpose, and each sentence adds value. The description is concise without unnecessary detail.

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

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

The description covers the main behavior and the key unitId scoping. It does not explain the required subjectSlug or the courseVariant parameter, though an output schema exists to describe return values. Given 5 parameters and moderate complexity, it is adequate but has 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 description coverage is only 40% (intent and requestId have descriptions). The description explains unitId behavior but does not clarify subjectSlug or courseVariant. With low coverage, the description should compensate more, but it only partially does.

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 'Starts' and the resource 'adaptive diagnostic', and it mentions the scoping by unitId. It is distinct from siblings in that it is the 'canonical' starter, but it does not explicitly name an alternative. This is clear enough for an agent to identify the tool's 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 explicit guidance on when to include a unitId versus omitting it, which is the key usage decision. However, it does not contrast with alternative tools or state when not to use it, so it is not fully explicit but gives useful context.

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

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

Annotations already declare readOnlyHint=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.