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

With no annotations provided, the description fully discloses the tool's destructive and irreversible nature, the exact scope of deletion, and the requirement for user confirmation. This exceeds the baseline for behavioral transparency, as it covers the most critical behavioral aspects.

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 extremely concise at two sentences. The first sentence front-loads the destructive warning and scope, and the second sentence adds the confirmation requirement. Every word earns its place with no redundancy.

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

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

For a single-parameter destructive tool, the description covers all essential information: what it does, what it destroys, irreversibility, and the mandatory user confirmation. The output schema exists, so return values need not be described. Nothing critical 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 schema coverage is 0% and the description does not explicitly explain the document_id parameter. However, the description's reference to 'deletes a document' makes it obvious that document_id is the document identifier. Since there is only one parameter, the meaning is clear from context, but the description adds no additional details about format, validation, or constraints. It partially compensates for the missing schema documentation.

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

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

The description states a specific verb ('deletes'), a specific resource ('document'), and explicitly lists the associated data destroyed (material, flashcards, quiz questions, answer history). It is unambiguous and distinct from all sibling tools, none of which perform deletion.

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 usage context: it is destructive and irreversible, and it explicitly instructs the agent to confirm with the user by stating the document title before calling. While it does not name alternatives, no other sibling tool performs deletion, so no alternative routing is needed. The confirmation requirement serves as a strong usage guideline.

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 no annotations, the description carries the full burden, and it handles that well: it discloses the side effect ('Writes the file'), the return behavior ('returns its path; it does not return the CSV text'), and the default output location. It does not mention overwrite behavior or permission requirements, but the core behavioral profile is transparent.

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 front-load the main purpose, then add return-value behavior, default path, and parameter details. There is no filler, repetition, or redundancy with the input schema.

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

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

For a three-parameter file-export tool with no annotations and an output schema present, this description is complete. It states the side effect, default path, override path, quiz-inclusion toggle, and return type, so an agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains output_path by giving the default path and how to override it, and it explains include_quiz with an explicit usage instruction ('Set include_quiz false to export only flashcards'). document_id is left implicit but is obvious from the tool name and resource phrasing.

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 ('Export'), a resource ('a document's flashcards and quiz questions'), and a concrete output ('Anki-importable CSV file on this machine'). This clearly distinguishes it from siblings like get_study_items or save_flashcards, which suggest retrieval or saving rather than file export.

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 makes the primary use case clear: produce an Anki-importable CSV file on disk. However, it never explicitly says when to prefer this tool over sibling tools such as save_flashcards, save_quiz, or get_study_items, so the guidance on alternatives is only implied rather than stated.

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 no annotations provided, the description carries the full burden. It discloses the ordering behavior, inclusion of never-reviewed items, and the side effect of rendering an interactive study widget in supporting hosts. It does not mention whether calling this modifies state (e.g., resets due dates), but the described behavior is otherwise transparent.

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: the first defines the core behavior and ordering, the second gives the usage directive, and the third discloses the widget side effect. 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?

The tool has a single required parameter, an output schema, and a clear behavioral description. The only missing context is the meaning of document_id and whether the call has side effects on scheduling state, but for a simple retrieval-style tool this is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain what document_id means or how it filters the due items, leaving the agent to infer that it identifies the document whose items are due. This is a gap, but the single parameter is self-descriptive enough to be minimally adequate.

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 ('Return'), a specific resource ('study items due for review now'), and a precise ordering rule ('most overdue first'), which clearly distinguishes it from siblings like get_study_items. It also explains the inclusion of never-reviewed items, adding scope precision.

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

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

The description explicitly says 'Use this to pick what to study next,' giving a clear usage context. It does not explicitly name alternatives or when-not-to-use, but the sibling list and the specific due-item scope make the intended use unambiguous.

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

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

With no annotations provided, the description carries the burden and does reasonably well: 'Return' signals a read operation, 'stored' indicates pre-existing content, and the 'only source' rule gives important behavioral guidance. It does not explicitly mention side effects or failure modes, but those are minor for a getter with an output schema.

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

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

Two purposeful sentences, front-loaded with the verb and resource. The second sentence is longer but earns its place by enforcing a critical content-source constraint with no wasted words.

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

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

For a simple one-parameter getter with an output schema, the description covers selection and invocation well. It would be slightly strengthened by explicitly directing the agent to call it before save_flashcards/save_quiz, but the 'only source' language already conveys that role.

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 only provides document_id: integer, and the description does not explicitly elaborate on that parameter. The phrases 'of a document' and 'this document's material' imply the identifier selects the target document, but the description does not mention where to source the ID from or how to handle missing documents.

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

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

The description uses a specific verb and object: returning the stored source material (text concepts) of a document. This clearly distinguishes it from sibling save/study/export operations and establishes it as the retrieval step for content generation.

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

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

It explicitly states that the returned material must be the only source when generating flashcards and quiz questions, and forbids outside facts or the model's own knowledge. It does not name sibling tools as alternatives, but the generation context makes the intended usage 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It is transparent about what the tool computes: progress counts and confidence breakdown based on each answered item's latest self-reported confidence. The word 'Return' implies a read-only operation, and no side effects are suggested, though explicit no-mutation guarantees are absent.

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 well-structured sentence starts with the core purpose and then lists the specific metrics returned. Every phrase adds information, and the confidence breakdown details are naturally appended without 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?

The tool is simple with one parameter, and an output schema exists, so return values do not need detailed explanation in the description. The description already enumerates all the metrics the agent can expect, making it complete enough to call the tool correctly.

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

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

The input schema only provides the parameter name 'document_id' and its type, with 0% schema description coverage. The description compensates by stating the tool returns progress 'for a document', clarifying that document_id identifies the document whose study progress is being queried. It doesn't fully explain the parameter, but the parameter is self-explanatory and the connection is clear.

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 ('Return') and a well-defined resource ('study progress for a document'), then lists concrete counts and a confidence breakdown. The semantic content clearly differentiates this from siblings like get_study_items or get_due_items, which focus on retrieving items rather than progress statistics.

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 the tool is for checking study progress, which suggests when an agent would use it. However, it does not explicitly state when to prefer this tool over alternatives like get_due_items or reset_progress, nor does it mention any exclusions or prerequisites.

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?

No annotations are present, so the description carries the full burden. It implies a read-only retrieval operation via 'already saved' and 'Return', and adds meaningful context about generated study items versus raw concepts. However, it does not disclose error behavior, auth requirements, or the prerequisite that study items must have been saved beforehand. Basic retrieval semantics are clear, but operational traits are under-specified.

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, no filler, and the core action is front-loaded. The second sentence earns its place by disambiguating from get_material. Appropriately sized and efficient.

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 and an output schema exists, so return structure is covered. However, the description omits useful context about the workflow: study items must be generated by save_flashcards or save_quiz before this tool returns anything, and document_id provenance is unclear. Still adequate for a basic getter, but with clear gaps.

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

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

The schema has a single document_id integer with no description (0% coverage). The description only says these are items 'for a document', which adds little beyond the schema's title 'Document Id'. It does not explain how to obtain the document_id, whether it comes from list_documents, or what constraints apply, so the description does not compensate for the lack of schema detail.

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 ('Return') and resource ('flashcards and quiz questions already saved for a document'). It also distinguishes itself from get_material by clarifying which tool returns generated study items versus raw source concepts, making it easy for an agent to select correctly.

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 names get_material as the alternative and explains the key difference: this tool returns generated study items, get_material returns raw source concepts. This provides clear when-to-use and when-not-to-use guidance for the most relevant sibling.

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 no annotations provided, the description carries the behavioral burden. It discloses that the operation persists the PDF's text as study material, returns document_id/title/concept_count, and positions get_material as the next read step. It does not cover error cases, duplicates, or permissions, but the core side effect and expected output are explicit.

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 action is front-loaded, followed by return values and a concrete next-step instruction. Every sentence earns its place.

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

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

An output schema is present, so return-value details are partially covered elsewhere, and the description adds valuable storage and next-step context. However, with no annotations and 0% schema description coverage, the missing input semantics around title and pdf_path leave the definition incomplete.

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 should compensate by explaining pdf_path and the optional title parameter. It mentions 'PDF' and title only as a return value, not as input semantics, and never clarifies that title is an optional label or how pdf_path should be supplied.

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 and resource: 'Ingest a PDF and store its text as study material.' It also names the return values, making the tool's function distinct from read/list/save siblings like get_material, list_documents, and save_flashcards.

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 workflow context by telling the agent to call get_material next before generating flashcards or quiz questions. It does not explicitly state when not to use this tool or compare it to alternative ingestion/listing tools, so it falls just 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?

With no annotations provided, the description carries the full disclosure burden. It conveys that this is a read-only listing operation by describing the output fields, but it does not explicitly state that no changes are made, nor does it mention any side effects, auth requirements, or performance characteristics. The implied read-only behavior is clear but could be more explicit.

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 wasted words. The first sentence states the core purpose and output fields; the second gives a direct usage instruction. It is perfectly sized and front-loaded for quick agent consumption.

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 zero-parameter, list-all tool with an output schema, the description is complete. It names the output fields, tells when to call it, and implies a non-mutating operation. Nothing an agent needs to correctly invoke this 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?

There are zero parameters, so the description has little to add beyond the schema. The schema coverage is 100% (trivially, since there are no properties). The description usefully explains the output semantics (fields included), which is a nice bonus. The 0-parameter baseline of 4 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('every stored document'), and enumerates the exact fields returned (id, title, concept count, flashcard count, quiz count). This clearly differentiates it from siblings like get_material or get_study_items by positioning it as a full-list discovery operation.

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

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

The description explicitly tells when to use the tool: 'Call this at the start of a session to discover document ids.' It gives a clear context of use, though it doesn't explicitly name when not to use it or point to an alternative tool. For a simple listing tool this is strong 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?

There are no annotations, so the description carries the full burden, and it excels: 'DESTRUCTIVE and irreversible' explicitly flags risk, and it details exactly what is erased, what is preserved, and the required user confirmation.

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, front-loads the critical destructive warning, and packs essential information with no filler. 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 single-parameter destructive tool, the description covers the action, consequences, exclusions, and required confirmation. An output schema exists, so the absence of return-value documentation is not a gap.

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

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

Schema description coverage is 0%, and the description does not explicitly explain the document_id parameter. However, parameter intent is reasonably inferable from the phrase 'a document's entire answer history' and the self-explanatory parameter name, which keeps this at an adequate level.

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 and resource: 'erases a document's entire answer history.' It also distinguishes its scope from deletion by stating 'Flashcards and quiz questions are kept,' which differentiates it from siblings like delete_document.

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 a strong precondition by instructing the agent to 'Confirm with the user before calling this tool,' but it does not explicitly state when to use this tool versus alternatives such as delete_document or get_due_items. The intended use is implied by the destructive/reset purpose rather than explicitly contrasted with sibling tools.

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

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

With no annotations, the description must disclose behavioral traits. It does mention that it returns stored cards with assigned ids and enforces a front/back requirement. However, it does not clarify whether saving appends to or replaces existing cards in the document, what happens on failure, or any permission requirements. This is a significant gap for a mutation 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 fluff. The primary action and key constraint are front-loaded, and every word adds value. It is appropriately sized for the tool's simplicity.

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

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

Given that this is a save operation with no annotations and an output schema (not shown), the description leaves out critical details: whether it overwrites or appends, validation rules for cards beyond front/back, and whether the document_id must pre-exist. For a mutation tool, these are essential 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 schema has zero descriptions, so the description must compensate. It adds the constraint that each card must have a front and a back, giving structure to the 'cards' array. It does not explain the format or allowed properties beyond that, and 'document_id' is left implicit as the target document. This partial compensation earns a 3.

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

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

The description clearly states the verb ('Save'), the resource ('generated flashcards'), and the destination ('to a document'). It also specifies the requirement that each card have a front and back, which is a distinct action. It is easily distinguished from sibling tools like save_quiz because it explicitly targets flashcards.

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

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

The phrase 'generated flashcards' implies the tool is for saving already-generated cards, but it does not explicitly state when to use it over alternatives like save_quiz, nor does it provide exclusions or prerequisites (e.g., document must exist). Usage is implied rather than explicit.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses validation rules (options required for multiple_choice, answer must be one of them) and the return behavior (stored questions with ids). It does not mention side effects or failure modes, but the disclosed information is valuable and goes beyond the schema.

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

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

The description is two sentences with no filler. The main purpose is stated first, followed by essential parameter constraints and return behavior. Every sentence earns its place.

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

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

The tool has 2 parameters and an output schema, and the description covers the critical input structure and return value. It does not mention whether document_id must exist or error conditions, but for a straightforward save operation this is sufficient. An agent has enough to call it correctly.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does this well for 'questions' by detailing required fields and constraints. 'document_id' is only implicitly covered as the target document, but that is adequate given its self-explanatory name. The description adds meaning the schema lacks.

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 (save), the resource (quiz questions), and the target (a document). It distinguishes from the sibling save_flashcards by explicitly naming quiz questions, so an agent can route correctly without ambiguity.

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

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

The description implies usage context by specifying the exact structure for quiz questions, and the sibling tool names make it clear save_quiz is for quizzes vs flashcards. However, it does not explicitly state when not to use it or mention alternatives, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden and delivers substantial behavioral disclosure: grading is automatic for quizzes while flashcards are self-reported, answers must be 'correct' or 'incorrect' for flashcards, and the tool returns is_correct plus updated progress. This adds meaningful behavioral context beyond the bare schema, though side-effect persistence and error cases are left unstated.

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 lean sentences, each earning its place: purpose first, then grading behavior with the answer constraint, then parameter values plus return values. No filler or repetition of schema 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 5 parameters, no annotations, and 0% schema coverage, the description covers the essential details: purpose, grading behavior, answer constraints, item_type values, confidence values, and return values. Minor gaps remain (semantics of document_id/item_id, error behavior, whether confidence applies to both item types), so it is strong but not fully exhaustive.

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, and it does: it enumerates valid item_type values ('flashcard' or 'quiz'), the answer constraint for flashcards, and the three confidence values ('guessed', 'unsure', 'confident'). document_id and item_id remain implicit as identifiers, but their roles are reasonably inferable from 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?

The description opens with a specific verb+resource pairing ('Record an answer to a study item') that clearly identifies the operation. It distinguishes this tool from siblings like save_flashcards and save_quiz (which create items) and get_study_items/get_due_items (which retrieve them) by framing it as the answer-submission 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 provides clear context: use this when recording an answer to a study item, and it explains per-type behavior (quiz auto-graded vs flashcard self-reported) plus the allowed answer values for flashcards. It does not explicitly name alternatives or state when-not-to-use conditions, 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.