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 annotations already indicate non-read-only, non-destructive, idempotent behavior. The description adds valuable context beyond those annotations: it can take a few minutes, it is free for signed-in students, and it uses a generator and verified resource catalog. The retry guidance about reusing requestId with identical input meaningfully complements the idempotentHint annotation.

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

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

The description is compact and front-loaded with the core action. Each sentence contributes useful information: purpose, access constraint, latency expectation, and retry behavior. It avoids fluff, though slightly more structure around parameter meaning could improve it.

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 mutating, idempotent tool with a timeout and an output schema, the description covers the key operational concerns: cost/access, expected duration, and retry handling. It does not explain prerequisites like how to obtain a valid subjectSlug or what should be passed in scope, but the output schema and sibling tools partially cover that 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 only 20%, with only requestId documented in the schema. The description broadly maps inputs to 'topic and available time,' but it does not explain subjectSlug, scope, timeAmount, or timeUnit semantics enough to compensate for the low schema coverage. More specific parameter guidance would be needed for reliable invocation.

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

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

The description states a specific action ('Creates and saves') on a clear resource ('trackable Fiveable study plan') with explicit inputs ('topic and available time'). It clearly identifies a creation operation distinct from the get/list/update siblings, though it does not explicitly name those alternatives.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives like get_study_plan, list_my_study_plans, or update_study_plan_tasks. It mentions that it is free for signed-in students, which implies an access condition, but it does not state when not to use the tool or which sibling should be chosen instead.

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, so the description does not need to restate safety. It adds meaningful behavior beyond annotations: it returns only a small set of passages rather than a full guide, and it discloses that one call consumes a full-content preview for free callers. This context helps an agent predict cost and granularity.

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: it states the output type, scope, intended use cases, an alternative, and a cost implication. The most important information is front-loaded before the usage guidance.

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 input schema, annotations, and existing output schema, the description covers the essential decision-making context: what the tool returns, when to use it, what it avoids, and its cost. It could name the alternative tool explicitly, but the phrase 'fetching a full guide' is clear in the context of the sibling tool list.

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 inline descriptions for query, intent, guideSlug, and subjectSlug already carry most of the meaning. The tool description reinforces the notion that query is a single question and that sections are a small set, but it does not substantially clarify maximumSections or maximumTokens beyond what their names, defaults, and constraints imply.

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 'a small set of passages from Fiveable study guides' relevant to 'one question,' which identifies the action, resource, and scope precisely. It also distinguishes itself from fetching a full guide, which sets it apart from related tools like get_study_guide.

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 to use this tool 'for narrow explanations, research questions, and checking student notes instead of fetching a full guide,' providing both positive use cases and an alternative. It also adds a cost constraint about consuming a full-content preview, which helps an agent decide whether to invoke 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 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 cover readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing the content of the response (definition, context, related terms) and the cost profile ('Cheap — usually under 1k tokens'), which helps an agent weigh this against heavier alternatives.

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

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

The description is two tight sentences, front-loaded with what the tool does, followed by when to use it and a cost note. No filler or repetition of schema details; every sentence serves a distinct purpose.

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 getter with a rich output schema, full annotation coverage, and complete parameter descriptions, this is sufficient. The description covers purpose, use case, response contents, and cost—nothing important is missing for correct selection and 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 100%, so the schema already fully documents termSlug, subjectSlug, and intent. The description adds no parameter-level detail beyond the schema, which is acceptable at the baseline of 3 given the high coverage.

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

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

The description states a specific verb and resource ('Returns the full definition, context and related terms for one AP key term') and explicitly names the intended use case (student asks 'what does X mean'). The word 'one' distinguishes it from list_key_terms, and the definition clearly differentiates it from search_content or get_cheatsheet.

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, concrete trigger: 'Use when a student asks what does X mean for AP vocabulary.' It does not explicitly name alternatives to avoid, but the use case is specific enough that an agent can decide when to invoke this tool over siblings.

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

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

Annotations already 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?

Despite readOnly/idempotent hints, the description adds important non-obvious behavior: adaptive tier dropping via recentCorrect/recentAnswered, preview-quota consumption, and token cost (roughly 300 tokens per question, more with images). It also discloses stimulus-set behavior and that a Question id enables answer submission.

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

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

Two dense paragraphs with front-loaded core purpose, then usage variants, then side effects/cost. No filler; the length is justified by the tool's 12 parameters and the non-obvious quota/cost behavior.

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?

Between the prose and the fully described input schema (100% coverage) plus an existing output schema, an agent has enough to select and invoke the tool: topic modes, answer-key defaults, tier adjustment, preview consumption, and cost are all covered.

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

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

Schema coverage is 100%, so baseline is 3. The prose adds value by explaining why recentCorrect/recentAnswered matter (drop to easier question types) and that topic matching accepts natural phrasing, going beyond the schema's mechanical descriptions.

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

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

The first sentence nails a specific verb and resource: it 'returns original, course-specific multiple-choice practice questions.' It further disambiguates by saying this is 'targeted or mixed practice, distinct from Fiveable's durable adaptive diagnostic,' so an agent can separate it from diagnostic and exam-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?

Gives concrete selection guidance: omit topic for whole-subject balanced practice, pass topic for targeted practice, and notes subject-specific source-based behavior. It explicitly distinguishes this from the adaptive diagnostic, though it stops short of naming the exact sibling to use instead.

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 establish the safe, read-only, idempotent profile. The description adds meaningful non-obvious behavior: it consumes one full-content preview for free callers unless access already covers the subject/feature, and it warns that a full guide can cost 3-8k 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 carry the key facts: return format, reference flexibility, usage context, quota cost, and token size. It is front-loaded with the most important information and has 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?

Given the output schema exists and the annotations cover the safety profile, the description provides the remaining operational context: size/cost, preview consumption, and when the tool is appropriate. Nothing critical is missing 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that guideSlug accepts 'a close approximation of its title', not just the canonical reference, which helps an agent pass user phrasing directly. The other params remain fully documented 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: 'Returns the full text of one Fiveable AP study guide as Markdown.' This clearly separates it from sibling tools like get_cheatsheet or get_content_sections, which involve different content types, and states the scope of exactly one guide.

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 an explicit use context: 'Suitable when a student asks to learn or review a topic.' It does not name alternatives or state when not to use it, so it falls short of a full when/when-not routing, but the context is clear enough to guide selection.

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, but the description adds valuable context: plan ids are stable, revision is included, and reading older plans never changes them. This goes beyond the structured annotations and helps an agent trust the read operation fully.

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 operation is front-loaded, followed by the most important usage note about revision and a clarity statement about non-mutation.

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 single-parameter read operation with a rich annotation set and an output schema present, the description covers what an agent needs: scope of access, stable identifiers, revision usage, and non-mutating behavior. No critical operational detail 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?

The schema has no description for planId and only provides a hex pattern, so the description must compensate. It does so implicitly by identifying the resource as 'one owned study plan,' which tells the agent that planId refers to an owned plan's identifier. The parameter name and pattern reinforce this, though an explicit mapping would have been slightly stronger.

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 ('Reads'), a clear resource ('one owned study plan'), and the key payload elements ('stable task ids, completion state and revision'). This distinguishes it from sibling tools like list_my_study_plans and get_study_guide, whose purposes are different.

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 concrete guidance: 'Use its revision for task changes,' which tells an agent when this tool's output is needed for a follow-up operation. It also clarifies that reading older plans is safe and non-mutating. It does not explicitly contrast with get_my_study_plans for listing, but the 'one owned study plan' phrasing makes the scope 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?

Beyond the annotations, which already declare read-only, idempotent, and non-destructive behavior, the description discloses a moderate token cost (2-5k depending on subject size) and the specific content of the response. This adds helpful context for the agent to manage 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?

Two sentences with no filler; the core return value is front-loaded, followed by a practical cost note. The description is efficiently structured and every sentence contributes to the agent's understanding.

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 only has two parameters, a complete output schema, and safety annotations, the description covers the key payload and cost behavior. It does not explicitly handle alternative selection among the many retrieval siblings, but that is a minor omission given the other structured signals.

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 both parameters are fully documented in the schema. The description adds little new meaning beyond framing subjectSlug as representing 'one AP subject' and noting the returned study guide slugs, which is ancillary rather than necessary.

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 full unit and topic outline for one AP subject, with every study guide slug in each unit. This distinguishes it from siblings like get_unit_overview or get_study_guide by emphasizing the whole-subject scope and its role as a course map.

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

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

It provides clear context on when to use this tool: for study planning and to locate individual study guides. However, it does not explicitly name alternatives or give exclusions, so it falls just short of a full routing rule.

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 read-only, idempotent, and non-destructive behavior; the description adds useful behavioral context beyond that, including the moderate token cost (1-3k tokens) and the kind of page returned. 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?

Two sentences with no filler: the first front-loads the action, resource, and content; the second adds only the relevant use case and cost. Every word earns its place.

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

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

For a simple read-only overview tool with an output schema, rich annotations, and fully documented parameters, the description covers purpose, when to use it, and cost. Nothing material needed by an agent to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents subjectSlug, unitSlug, and intent, including source guidance ('from get_subject_outline', 'Use list_subjects'). The tool description contributes no additional parameter meaning, which is acceptable at the baseline of 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 names a specific verb ('Returns') and resource ('overview page for one unit of an AP course') and enumerates the contents: coverage, exam weighting, topics, and study plan. It is clearly distinguished from sibling tools like get_subject_outline or get_study_guide by being scoped to a single unit's overview.

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?

States when it is suitable: 'when a student is reviewing a whole unit,' providing clear context. It doesn't explicitly name alternatives or when-not-to-use, but the use case is well enough defined to route an agent appropriately among the listed siblings.

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

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

Annotations already signal readOnlyHint, openWorldHint=false, idempotentHint, and non-destructive behavior, so the description's extra context is a bonus. It adds useful behavioral nuance by noting that academic year is included 'when known', mentioning readable-artifact readiness, and explicitly scoping out user-generated content. There is no contradiction with annotations.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the second sentence earns its place by drawing a clear boundary around what the tool does not return.

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

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

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

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

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

Schema description coverage is 0%, so the description bears the burden of explaining the five parameters, but it does not explain limit, cursor, unitNumber, subjectSlug, or courseVariant directly. The phrase 'course and unit PDFs' weakly maps to subjectSlug and unitNumber, and 'course variants' hints at courseVariant, but limit and cursor remain entirely unaddressed.

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

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

The description states a specific verb ('Find') and a specific resource ('approved Fiveable course and unit PDFs'), and enriches it with concrete details about course variants, academic year, source links, and artifact readiness. It also explicitly excludes user galleries and personal visuals, which helps distinguish it from broader content-listing tools.

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

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

The description gives a clear scope and one meaningful exclusion, but it does not name alternative tools or specify when to use this list tool versus fetch tools like get_cheatsheet or search_content. The intended usage is mostly implied by the word 'approved' and the list-oriented verb, rather than explicitly contrasted with siblings.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: stable ID ordering, pagination semantics with unchanged filters, the fact that only summaries are returned, and the cost characteristic ('Cheap'). This helps an agent reason about repeated calls and performance.

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 tight sentences with no filler. It front-loads the core purpose, then adds pagination, return-content, and cost details that each earn their place. The one-word 'Cheap' is concise but informative.

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

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

Given the tool has an output schema, the description does not need to detail return fields. It sufficiently covers filtering, pagination, content scope, and cost, making it complete enough for an agent to select and invoke the tool correctly without missing critical behavioral expectations.

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 71%, so the schema covers most parameter meanings. The description adds useful semantics by naming the filter dimensions (FRQ type, unit, excluded IDs) and explaining pagination behavior tied to cursor usage, complementing the schema without fully re-documenting every 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 clearly states the action ('Lists'), the resource ('Fiveable's free-response practice prompts'), and the scope ('for an AP subject'). It also distinguishes itself from the sibling get_frq tool by explicitly noting it returns prompt ids and summaries rather than full prompts.

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

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

The description implies when the tool is useful: listing filtered FRQ prompts in paginated form. However, it does not explicitly name an alternative like get_frq for full-prompt needs or state when not to use this tool, so the guidance remains implicit rather than explicit.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description adds useful extras: pagination is alphabetical, results contain stable slugs, and the call is 'Cheap' from a cost/performance standpoint. 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 tight sentences deliver the core behavior, use cases, result relevance, and a performance note with zero fluff. The primary action is front-loaded, and the 'Cheap' note earns its place as operational guidance.

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

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

Given an output schema, annotations, and full parameter descriptions, the description covers the essential behavioral and usage context. It could be slightly stronger by explicitly naming get_key_term as the follow-up for full definitions, but the slug reference makes that connection reasonably clear.

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 explains page, limit, letter, and subjectSlug. The description's 'paginated alphabetically' adds ordering context, but it does not add meaningful parameter-level meaning 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?

States the exact action ('Lists'), specific resource ('key vocabulary terms'), and scope ('for an AP subject'), with pagination and alphabetical ordering. It also distinguishes itself from the sibling get_key_term by noting that results include stable term slugs for full definitions.

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

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

Provides clear use cases: building flashcards and checking expected vocabulary, which helps an agent decide when listing is appropriate. It implies get_key_term for full definitions via 'stable term slugs' but does not explicitly name alternatives or say when not to use this tool.

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

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

Annotations already 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?

Beyond the annotations, the description discloses that the report may lead to normal support follow-up, that Fiveable resolves the content and reporter identity, and that requestId should be reused on retries. These are meaningful behavioral traits that the annotations alone do not express, and there is no contradiction with readOnlyHint=false or idempotentHint=true.

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?

Every sentence earns its place: the trigger condition, the follow-up effect, the content boundaries, the identity-handling note, and the retry instruction. The description is compact, front-loaded, and contains no fluff 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?

For a 5-parameter reporting tool with an output schema and supporting annotations, the description covers the essential behavioral context: when to call it, what to exclude, what will happen after submission, and how to handle retries. Nothing critical 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?

The input schema already describes contentId, description, and confirmReport, and the description adds helpful semantics for requestId by framing it as an idempotency key to reuse on retries. It also reinforces that description must contain only the reported issue and not transcript or personal data, although contentType semantics are left entirely to its enum.

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 makes the tool's sole purpose unmistakable and distinguishes it from the surrounding get/list/score siblings, none of which perform this reporting action.

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 states an explicit trigger condition: 'only when the student explicitly asks to report it.' It also gives clear exclusions ('Do not automatically report disagreements or send conversation history, unrelated notes, or personal information'), telling the agent when not to use the tool and what content must not be included.

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 annotations, disclosing that sign-in is required, that a free preview is included with further scoring limited to eligible accounts, that the attempt is saved to Fiveable progress, that the call returns a pending job requiring polling, and that requestId should be reused for retries. This covers auth, quota, side effects, async return behavior, and idempotency guidance—exactly the kind of behavioral context annotations alone do not 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?

Five sentences, each carrying distinct information: core purpose, photo transcription workflow, prompt image rationale, auth/eligibility, and async result/retry behavior. The most important scoping information is front-loaded in the first sentence, and no sentence is 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?

Given the tool's complexity—11 parameters, 6 required, image arrays, an output schema, and a multi-step transcription workflow—the description covers the critical non-schema aspects: when transcription confirmation is required, auth and eligibility, persistence of the attempt, return type, and polling/retry. The output schema presumably documents the return value shape, so the description need not repeat it. The only minor omission is whether pasted (non-photo) submissions also require transcription confirmation, but the schema's const true on transcriptionConfirmed and the workflow description make this inferable.

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 91%, so the input schema already documents most parameter meanings. The description reinforces the transcription-confirmation requirement and the requestId retry rule, but these are already present in the schema. It adds little genuinely new per-parameter semantics beyond the schema, so 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 first sentence, 'Scores a student's existing FRQ even when it did not come from Fiveable,' is a specific verb+resource statement that clearly distinguishes this tool from the sibling score_frq_response. The title reinforces the purpose: 'Score an uploaded or pasted FRQ.' An agent can immediately identify what this tool does and how it differs from the standard FRQ scoring tool.

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 workflow instructions: if the student attached photos, the host AI must first transcribe the prompt and response, show the transcription for confirmation, then call this tool. It also directs the agent to poll get_scoring_result for the result and reuse requestId for retries. However, it never names the alternative tool score_frq_response directly or states an explicit 'use the other tool when the FRQ came from Fiveable,' leaving that distinction implied by 'even when it did not come from Fiveable.'

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 annotations, the description discloses important behaviors: the submission is saved and asynchronous, a scoring job id is returned for later retrieval, requestId enables idempotent retries, and there is a one-free-score quota for signed-in students. This gives the agent a clear picture of side effects and constraints without contradicting the annotations.

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

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

The description is four short sentences with no fluff. Each sentence contributes distinct value: the action, supported content, exclusions and return behavior, and idempotency/quota. Important information is front-loaded and the rest is compact.

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 nine parameters and nested objects, the description covers the essential operational context: scope, exclusions, async behavior, job id retrieval, idempotency, and the free-score constraint. The output schema exists, so return-value details are not necessary, but a bit more guidance on optional modes like sample project versus the student's own project would make it fully 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 low at 22%, so the description needs to compensate. It does summarize the major payload categories—text, subparts, drawings/photos, LEQ selection, CSP code, and Business project references—and explains requestId's retry role, but it leaves several parameters like intent, promptVariantId, and businessProjectPracticeMode to be inferred from 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 states a precise action: submits the student's own response to a Fiveable practice FRQ for saved, asynchronous scoring. It also distinguishes this tool from teacher assignments/exams and names the specific supported content types, making the tool's scope unmistakable.

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 establishes when to use the tool: for student practice FRQs that should be saved and scored asynchronously. It adds the exclusion of teacher assignments and exams, though it does not explicitly name alternative sibling tools such as score_external_frq_response or check_practice_answer.

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 cover idempotency and non-destructiveness, and the description adds meaningful behavior: it returns one adaptive question at a time and creates durable diagnostic progress. 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 compact, purposeful sentences with no filler. The action is front-loaded, and each sentence adds distinct value: scope behavior, return behavior, and state persistence.

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 annotations and output schema, the description covers the core behavior and scoping rules well. It does not fully explain prerequisites for the 'connected student' or the semantics of subjectSlug/courseVariant, which prevents a 5.

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 compensates well for unitId by explaining course-wide vs unit-scoped behavior, and the schema documents intent and requestId. However, required subjectSlug and courseVariant rely mostly on name, pattern, and enum for meaning, so the low schema coverage is only partially compensated.

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

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

The description opens with a specific verb and resource ('Starts Fiveable's canonical adaptive diagnostic') and clearly differentiates scope by unitId. It also separates this tool from siblings like get_diagnostic_results and submit_diagnostic_answer by describing the starting action rather than retrieving or submitting.

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: use it to begin the diagnostic for the connected student, optionally narrowed to a specific unit via unitId. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

The annotations already indicate mutation is expected (readOnlyHint=false) and idempotency is supported. The description adds useful behavioral context: it saves exactly one answer, returns feedback plus one adaptive next question, and accepts multiple answer formats. This goes beyond the 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?

Two tightly written sentences front-load the core action and result, then add input-format and batching constraints. There is no redundant or filler content.

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

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

For a one-shot diagnostic answer submission, the description covers what is saved, what is returned, accepted input forms, and the per-call limit. Combined with the schema descriptions for requestId and intent, the tool definition is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is only 40%, so the description partially compensates by clarifying the answer parameter can be an option letter, full text, or answer id. The remaining parameters (sessionToken, questionId) are self-explanatory or already described in the schema, and the 'one question per call' note adds scope clarity.

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 action ('Saves one answer'), names the exact resource ('active Fiveable diagnostic'), and describes the return behavior ('feedback plus exactly one next adaptive question'). This clearly distinguishes the tool 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 gives clear context for when this tool is appropriate: answering the current question in the student's active diagnostic. It emphasizes 'one question per call' and the diagnostic-specific scope, though it does not explicitly name alternatives or state when not to use it.

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

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

With annotations already covering idempotency and non-destructiveness, the description adds useful behavioral context by explaining the side effect of recording progress and the return of correctness plus explanation. It does not repeat conflict behavior, but the schema and idempotentHint annotation already capture that.

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 primary purpose and scoping constraint before the return behavior, and every clause 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?

Given moderate complexity, full schema coverage, the output schema, and the idempotency annotation, the description is complete: it identifies the actor, the prerequisite question source, the effect of recording progress, and the returned information. No critical gap remains for correct invocation.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description adds the multiple-choice context and that questionId must come from a Fiveable MCP-served question, but it does not go beyond what the parameter descriptions already provide.

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 action—'Records the signed-in student's answer'—and clearly defines the resource as a multiple-choice practice question. It adds the important consequence that the answer 'counts toward their Fiveable progress,' which distinguishes it from sibling tools like check_practice_answer that likely only evaluate without recording.

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: use this tool when a signed-in student submits an answer that should be recorded and count toward progress, and the question must have been previously served by Fiveable MCP. It does not explicitly name alternatives or exclusions, but the scoping is sufficiently clear for an agent to choose this tool over related practice-checking 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 carry readOnlyHint=false and idempotentHint=true. The description adds meaningful context: the data is self-reported planning, not assessed work, and retries with identical input are safe. It also implies optimistic concurrency via 'latest revision' without contradicting 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, each serving a purpose: action, boundary, and operational requirement. Information is front-loaded and there is no filler.

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

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

For a mutating tool with idempotency and an output schema, the description covers the key operational details (revision, requestId, ownership, self-reporting). It doesn't spell out stale-revision failure behavior, but 'latest revision' and safe retry language imply it; this is adequate given the annotations.

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 25%, so the description must compensate. It adds meaning for requestId (unique, retry-safe) and expectedRevision (latest revision), but planId semantics are only implicit in 'owned plan tasks' and the tasks array structure is left to the schema. Partial compensation for the coverage gap.

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

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

The description opens with a specific verb ('Marks') and resource ('owned plan tasks'), and clarifies the action is toggling completion status. It explicitly distinguishes itself from quiz scoring/practice submission, separating 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?

It states the intended context ('at the student's request') and a firm exclusion ('never a quiz score or practice submission'), which tells an agent when not to use it. It also provides usage prerequisites (latest revision and unique requestId) though it does not explicitly name alternative sibling tools.

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