Talkfirst

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

Annotations already declare this as a non-readOnly, non-destructive write, so the safety bar is partly covered. The description adds real behavioral context beyond that: duplicate cards are silently skipped, and the 'back' field must use the user's ui_lang pulled from today/profile. It stops short of describing the response or any rate/limit behavior.

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

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

The JSON example is front-loaded and is exactly the kind of concrete artifact an agent needs for an unspecified object array, with the dedup and entry-rule notes following compactly. No sentence is filler given the 0% schema coverage it has to offset.

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 write tool with an untyped schema and no output schema, the description covers payload shape, dedup behavior, and field-language rules, which is most of what is needed. Minor gaps remain: no batch-size limits and no description of the creation result/return, though the absence of an output schema lowers that expectation.

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 single parameter is an untyped array of loosely-typed objects, so the description carries the full burden and largely does so – it enumerates the fields (front, back, kind, example_front, example_back, tags) and gives semantics for each, including the 'word|phrase' enum for kind. It lacks per-field type/nullability detail, but compensates well for the schema gap.

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

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

The description states a specific verb and resource ('Add cards', with the title clarifying flashcards) and spells out the exact payload shape, so the agent knows it is creating vocabulary cards. It does not, however, distinguish itself from the sibling vocab_add, leaving the agent to guess which of the two add-style tools to pick.

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?

There is implied usage via the entry-rule hint ('one card is one word in its dictionary form ... or one whole ready phrase') and an external pointer ('entry rules: docs("vocab")'), plus the useful 'Duplicates are skipped' behavior. But there is no explicit when-to-use vs when-not guidance relative to alternatives like vocab_add or mark_known.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive write, so the safety profile is covered. The description adds one genuinely useful behavioral detail: omitting 'chunk' falls back to the right side of the correction or the whole rephrasing as a formulation. It says nothing about failure modes, duplication, or what is mutated, so it clears the lowered bar but does not enrich it much.

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 single dense sentence front-loads the purpose but then crams three parameter definitions plus a conditional fallback into semicolon-separated fragments, which hurts readability. Nothing is outright wasted, but the structure is tangled rather than crisp.

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 write tool with annotations covering the safety profile and no output schema, the description does not need to explain return values. It covers most parameters but omits the required turn_id and any notion of error or duplicate handling, so it is adequate rather than complete.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It usefully defines 'part' (correction or upgrade), 'index' (number in the review), and 'chunk' (expression number, with a documented default behavior). However, 'turn_id' — a required parameter — is never explained, leaving one of three required inputs undocumented in both schema and description.

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

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

The opening clause 'Add to the vocabulary from a line review' does name a verb (add) and a resource (vocabulary entry), but 'line review', 'chunk', and 'formulation' are opaque jargon and the description never distinguishes this from the sibling vocab_add or add_cards. The purpose is only partially recoverable without domain knowledge of the app's review workflow.

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?

There is no guidance on when to use this tool versus vocab_add, add_cards, or practice_phrase, all of which appear to touch vocabulary. The description explains internal field mechanics rather than selecting conditions, leaving the agent to guess the triggering context.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false) already signal a benign, non-destructive mutation, lowering the bar. The description usefully clarifies what mode and delay_ms mean, but doesn't disclose whether the attempt is stored, scored, or fed into SRS, which matters for a non-idempotent write.

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 tight sentence front-loads the purpose and then covers the two ambiguous parameters with no wasted words. Dense but readable; earns nearly every clause.

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 six parameters, 0% schema coverage, and no output schema, the description should explain the return (score? feedback?) and the remaining parameters such as mime and card_id. It leaves the agent unclear on the response shape and on required-field 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 carry the load, and it explains two non-obvious params: mode (read/recall) and delay_ms (reaction time). However, mime (required), card_id, and audio_b64 receive no explanation, leaving half the parameters undocumented.

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 (Assess) and resource (a pronunciation recording of the phrase text), which an agent can distinguish from siblings like practice_phrase, quiz_audio, and reference_audio. Sibling differentiation is implied by the pronunciation-assessment focus rather than explicit.

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 never says when to call this versus alternatives such as practice_phrase or quiz_audio, nor any prerequisites like having a phrase/card in hand. Usage is only inferable from the tool name and the mention of reaction-time measurement.

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

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

Despite annotations already declaring this a destructive, non-read-only, idempotent write, the description adds substantial behavioral context beyond them: a level counts as known for about a month along with all lower steps, the word leaves quizzes on those steps and returns once for a check in about three weeks, and 'none' sends the word back to practice. It also discloses output-side handling of terms not found in the vocabulary ('unknown'), which is exactly the kind of side-effect detail an agent needs.

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?

All the content earns its place, but the structure is a dense run-on that embeds the parameter definition mid-sentence and mixes semantics, side effects, and edge cases with semicolons. The core action is front-loaded, yet the level definitions and timing rules are hard to scan. Valuable information delivered in a suboptimal layout.

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-parameter mutating tool with annotations covering the safety profile and no output schema, the description is nearly complete: it documents the parameter, the side effects on quizzes and repetition timing, and unknown-term handling. It does not state what happens on exceeding the 200-item cap or what the call returns, but given the annotations and absence of an output schema these gaps are minor.

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 single 'items' parameter is an untyped array of open objects, so the description carries the full burden — and it does. It specifies the item shape, the enum values (none|recognize|recall|listen|say), the max count (up to 200), and defines each level (recognize = understands, recall = translates into it, listen = understands by ear, say = says from memory, none = does not know it). This fully compensates for the empty 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 specific verb and resource: it records how well the user knows words of the active language, driven by the user's own answers. It also distinguishes itself from the sibling mark_known by noting it applies 'the same marks as mark_known with skills,' so an agent can differentiate the two. It stops short of a crisp one-line statement of purpose because the details of levels and timing are woven in before the core action is fully framed.

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

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

Usage is implied: this is the tool to call when you have the user's self-reported knowledge levels for a batch of terms. The mention of 'the same marks as mark_known with skills' signals a relationship to that sibling but does not state when to choose calibrate over mark_known, nor any prerequisite (e.g., an active language or session). No explicit when/when-not guidance is given.

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 mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description adds genuinely useful behavioral context missing from those hints – the card is suppressed from both review and quizzes until the window elapses – but says nothing about reversibility, permission needs, or interaction with the existing SRS schedule.

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

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

A single sentence with zero filler, front-loading the action, the duration parameter with its range, and the resulting effect. Nothing needs trimming.

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 mutating tool with no output schema, the description covers the effect and the days range but omits the default value, how to undo a deferral, and how this differs from skip_card/mark_known. Adequate 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?

Schema coverage is 0%, so the description must carry parameter meaning. It does clarify the days parameter's valid range (1-365) and meaning, but the schema's default of 3 is never mentioned and card_id is left entirely unexplained. Partial compensation only.

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 ('Postpone') and resource ('card') and explains the outcome: the card does not appear in review or quizzes until the deferral expires. It does not, however, explicitly distinguish itself from the close sibling skip_card, so an agent must infer the difference.

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 appropriate (you want a card excluded from future reviews/quizzes for a period), but never states when to prefer it over skip_card, mark_known, or remove_word. No exclusions or prerequisites are given.

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 useful format context beyond that (base64-encoded, mp3, or the learner's own recording), but says nothing about error behavior when a turn has no audio or any size/rate considerations.

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 with no filler; the return format is stated immediately. Only the ambiguous 'for the window' phrase detracts from an otherwise efficient structure.

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 of two identifiers with no output schema, the description adequately conveys the return format. It remains incomplete on what session_id vs turn_id mean and on failure conditions, which matters more given the 0% parameter documentation.

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% for two required parameters, so the description must carry full semantic load. It only vaguely implies a 'turn' is needed and says nothing about what session_id identifies or how the two relate, so the burden is largely unmet.

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 the resource (audio of a conversation line) and its format (mp3 or learner's recording, base64), so an agent can tell it returns audio rather than text. However, it uses a noun phrase with no verb and the phrase 'for the window' is unclear jargon, leaving the exact action (retrieve) to inference.

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?

There is no statement of when to use this tool versus alternatives. Siblings such as dialogue_turn (likely the text of a turn), quiz_audio, and lesson_audio are not referenced, and no prerequisites or ordering (e.g., must have an active dialogue session) are given.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this tears down state and is not repeatable. The description adds genuinely useful operational context about polling dialogue_result for late reviews, but it does not confirm the session is destroyed or whether results survive 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?

A single compact sentence with the action front-loaded before the parenthetical caveat. Efficient, though the cryptic 'summary.pending > 0' reference packs a lot of unstated context into a short clause.

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 no output schema, the description carries the burden of describing what comes back, and 'return the result' is notably vague about the response shape. The dialogue_result caveat partially compensates, and annotations cover the destructive profile, making this adequate but 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% and the description never mentions session_id, so the sole required parameter is explained by neither structured data nor prose. The name is fairly self-evident in a dialogue context, but the description does not compensate 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?

States a specific verb and resource ('End the conversation') that clearly distinguishes it from dialogue_start, dialogue_turn, and dialogue_state. It also implies a return value, though the pairing with dialogue_result is only partially explained, so sibling differentiation is present but not fully sharp.

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 parenthetical about late reviews arriving via dialogue_result while summary.pending > 0 hints at when to follow up with a different tool, which is real usage guidance. However, it never states when to call this versus letting a dialogue lapse, nor any precondition for ending, so guidance is implied rather than explicit.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: active-profile scoping, newest-first ordering, and the exact returned fields, which matters because there is no output schema. It does not explain limit/pagination behavior.

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

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

A single compact sentence, front-loaded with scope and ordering, followed by the return fields. The field list is dense but justified because no output schema exists.

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?

Because there is no output schema, the field enumeration is valuable and makes return values clear. The main gap is the undocumented limit parameter, which affects how the agent should call the 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?

There is one parameter, limit, with a default of 10, but schema description coverage is 0% and the description never mentions it. It therefore does not compensate for the missing parameter documentation, leaving the agent to guess the meaning and bounds of limit.

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

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

The description clearly states that it returns recent conversations for the active profile, newest first, and enumerates the fields. It is distinguishable from single-session siblings like dialogue_result, though it does not explicitly name alternatives.

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

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

It implies use for viewing recent conversation history but gives no explicit when-to-use guidance, prerequisites, or comparison to dialogue_result or dialogue_state. The agent must infer when this is the right tool.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered by structured data. The description adds real value by describing the components of the returned payload (plan, brief, lines, summary, expectations, pending), which is meaningful since there is no output schema, but it says nothing about scoping, partial results, or what happens for a session with no completed dialogue.

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?

It is a single sprawling sentence with nested parentheticals ('the summary (after the end: corrections, ... expectations: whether they were met; pending: ...)') that is hard to parse. 'The whole conversation' is reasonably front-loaded, but the structure is disorganized and does not separate return content from usage.

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 no output schema, the description does the necessary job of describing the returned structure, which is its strongest contribution. However, it omits what the tool actually does, how to obtain session_id, and any usage context, so it is incomplete for an agent deciding 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?

The single parameter session_id has 0% schema description coverage, so the description must carry the meaning of the parameter, yet it never mentions session_id at all. The agent gets no guidance on what a session id is or where it comes from.

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 enumerates the contents of the result ('plan, brief from the chat, lines with pauses and reviews, the summary...'), which hints at a retrieval of a full conversation record, but it never states a verb like 'return' or 'retrieve' and reads as a data-structure gloss rather than a statement of what the tool does. It offers some differentiation from siblings like dialogue_history or dialogue_state via the enumerated components, but the action itself is left implicit.

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?

There is no when-to-use guidance and no mention of alternatives. With close siblings (dialogue_history, dialogue_state, dialogue_audio, dialogue_end) in the same namespace, the description does nothing to tell the agent when this tool is the right pick versus those.

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

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

Annotations only declare the generic profile (not read-only, not idempotent, not destructive), so the description adds meaningful value: new target phrases are written into the vocabulary and a non-vocabulary string is an error, plus the free-plan restriction. These are real side-effect and failure-mode disclosures beyond the annotation set, though the return/start behavior itself is not described.

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 content is dense and almost every clause conveys needed information, but it is delivered as a single rambling paragraph with semicolon-chained field notes, not front-loaded into scannable lines. An agent must parse the wall of text to find per-parameter rules.

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 6-parameter tool with no schema descriptions and no output schema, the description covers parameters, side effects, error conditions, and plan constraints well. It is slightly incomplete on what starting actually returns (session/widget handle) and never states the required follow-up flow with dialogue_turn/dialogue_end.

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 burden and largely succeeds: topic semantics, brief content and its 2000-char limit, targets count (up to 10) and the exact string-or-{"term","meaning"} format with vocabulary-error rule, expectations and its 500-char limit, hints values (end/live) with behavior, and scene-vs-topic interplay. Each of the 6 parameters gains meaning the bare schema does not 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 opening clause 'Start a voice conversation in the widget from a task' gives a specific verb (start) and resource (voice dialogue widget), which clearly distinguishes it from siblings like dialogue_turn, dialogue_end, or dialogue_state. It stops short of naming those siblings or explicitly stating when to pick this one over them, so it lands at a strong-but-not-perfect 4.

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 embeds real conditional guidance: an empty topic means the director picks one, and on the free plan an own topic/brief is unavailable so only scenes may be used (with the list surfaced in the error). It never names an alternative tool, but the plan-gating and scene-vs-topic rules give the agent clear context for correct invocation.

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 a modest signal about the content returned (lines, pauses, finished reviews), but says nothing about freshness, mutation of session state, or how this differs from history.

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

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

One short, front-loaded sentence with no waste. It is appropriately sized, though the fragmentary phrasing (no verb) slightly undercuts clarity.

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 no output schema, the description is the only place to explain what 'state' actually returns and how it relates to sibling tools; it neither details the return nor distinguishes itself, leaving the agent to guess between dialogue_state, dialogue_history, and dialogue_result.

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 is one parameter, session_id, with 0% schema description coverage, and the description does not mention it at all — no format, source, or meaning. Although the name is self-explanatory, the low coverage means the description should compensate and it does nothing.

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 the resource (an ongoing conversation's state) and lists what it contains (lines, pauses, finished reviews), which is more than a bare restatement of the title. But it uses a noun phrase rather than a verb, never states that it retrieves/reads state, and gives no differentiation from close siblings like dialogue_history or dialogue_result.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With six sibling dialogue_* tools (dialogue_start, dialogue_turn, dialogue_history, dialogue_result, etc.), the description should route the agent but does not.

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

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

Annotations already establish this is a mutating, non-idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds useful behavioral detail about gap_ms timing and what 'last' does (save without a partner reply), but says nothing about responses, side effects, or what happens on a normal turn.

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?

Content is dense but relevant and front-loaded with the core concept. The semicolon-chained clauses and quoted 'End' make it a run-on that is harder to parse than necessary, though little is truly wasted.

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 non-idempotent mutation tool with no output schema and zero schema description coverage, the description covers the trickiest parameters but omits session_id/mime and gives no sense of the conversation lifecycle or return. It is adequate but incomplete for a 5-param tool in a multi-tool dialogue family.

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 carry parameter meaning; it explains gap_ms (timing between partner and learner lines), 'last' (End behavior), and implies audio_b64 ('audio in base64'). However session_id and mime are entirely unexplained in both schema and description, leaving two of five params undocumented.

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 frames the tool as 'the learner's line in a conversation' with audio in base64, which conveys the resource but never states a clear action verb (send/record/submit). It loosely distinguishes itself from siblings like dialogue_start/dialogue_end via the 'partner's line' and 'End' framing, but an agent must infer that calling it submits the turn.

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

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

No explicit guidance on when to use this versus dialogue_start, dialogue_end, or dialogue_audio, even though those siblings clearly overlap. The only partial hint is that 'last' is the line sent on 'End', which implies an ordering, but the agent is left to infer the overall conversation flow.

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, non-destructive, closed-world behavior, so safety is covered. The description adds genuinely new behavioral context: the tool is dual-mode and its return content differs by whether topic is supplied (and enumerates the topic names). It stops short of describing the response format beyond 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?

One sentence, no filler, front-loaded with the tool's identity and then immediately branching into the two modes with a parenthetical enum. Nothing to trim.

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 no output schema, the description usefully previews both return shapes and the topic vocabulary, and annotations cover the safety profile. It is close to complete for a one-parameter lookup tool; the only gap is how topics relate to sibling surfaces such as lessons or plan.

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 sole parameter has no schema description, so the description must carry the load — and it does, explaining that an absent/empty topic yields the topic list while a supplied topic yields that topic's text, plus the set of valid topic values. Only the exact accepted spelling/format of topic values is left unstated.

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

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

States a specific verb-and-resource pattern: it returns reference documentation, and it explicitly enumerates its two modes (topic list vs. topic text). The dual-mode framing distinguishes it from a plain 'topics' or 'lessons' lookup, though it never names those siblings. Purpose is clear but not explicitly differentiated from adjacent tools.

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

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

Gives explicit invocation guidance per mode: call with no topic to get the list of topics and when to read them; call with a topic to get that topic's text. It does not say when to prefer this over siblings like 'topics', 'lessons', or 'plan', so the routing guidance is incomplete.

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/non-destructive, so safety is covered. The description usefully discloses that the payload is base64 mp3 chunked at 2 MB, which is real behavioral context, but it does not say whether the chunk is browser-safe, how large the total can get, or whether repeated calls with the same part are stable.

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 dense sentence with no wasted words, front-loaded on the resource. But its compactness comes at the cost of clarity — the "parts"/"part" confusion is a direct product of cramming everything into one clause.

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 tool with no output schema, the description does hint at the return format, which is a plus. It still omits how to drive the `part` parameter, what lesson_id refers to, and any indication that multiple calls are the intended pattern, leaving the agent under-equipped 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 0%, so the description must carry the parameter burden. It never explains `lesson_id` (where it comes from) and, worse, discusses a nonexistent "parts" parameter instead of the real `part` integer, leaving the indexing/default semantics of `part` ambiguous.

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 the resource (lesson audio) and implies retrieval, and the "lesson" qualifier does separate it from sibling audio tools like dialogue_audio, quiz_audio and reference_audio. However, the verb is never stated and the phrase "for the window" is cryptic, so the purpose is only roughly graspable.

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?

There is no guidance on when to fetch lesson audio versus the sibling audio tools, nor any explanation of how to page through parts (e.g. increment `part` until reaching the total). The reader must infer the whole retrieval loop.

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 cover the safety profile (mutation, non-idempotent, closed-world), and the description adds real behavioral context beyond them: work is asynchronous ("audio and assembly run in the background"), the immediate return is {id, status: building}, and scenario errors surface synchronously by scene number. That async/error contract is exactly what an agent needs for a long-running build.

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?

Front-loaded with the action ("Build a lecture lesson"), then the immediate return and the background/error behavior. Slightly dense with parentheticals and a docs pointer interrupting the first clause, but no wasted sentences.

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 no output schema, the description carries the return contract and does it well (id + status: building, async completion, error timing). For a one-parameter create tool the only remaining gap is the concrete scenario format, which is offloaded to docs by design.

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 is a single required parameter (scenario) with 0% schema description coverage, so the description must compensate. It characterizes the value as a "v2 scenario" with "format, rules and an example" and points to docs("lessons"), which is helpful, but it does not inline the scenario shape, so the gap is only partially closed.

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

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

States a specific verb and resource ("Build a lecture lesson from a v2 scenario"), so the agent knows it creates a lesson audio/scene artifact. It gives no differentiation from siblings like lesson_audio, lesson_open, or lesson_get, so the agent must infer the boundary itself.

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

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

Usage is implied by the name and verb, and it routes the agent to docs("lessons") for the scenario format, which is useful setup context. However, it never states when to prefer this over lesson_audio or lesson_get, nor any prerequisites, so guidance is only implied.

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 structurally. The description adds that the response includes status, scenario, timing, and progress, which is modest but real value beyond the annotations; it does not describe format, pagination, or error behavior.

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

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

A single compact fragment, front-loaded and free of filler. It is arguably under-specified rather than overly verbose, but as conciseness it is 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?

For a read-only tool with no output schema, the description gives at least a preview of the returned fields, and annotations carry the safety context. Still missing are the meaning of lesson_id and any hint of how the result relates to sibling lesson tools, leaving gaps 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 single required parameter lesson_id has 0% schema description coverage, and the description never mentions it or its acceptable values (e.g., whether it is an ID, slug, or the same identifier used by lesson_open). With only one param the burden was small, yet the description does not compensate 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 fragment 'The whole lesson for the window' plus the name/title conveys that it fetches a complete lesson, and it lists the returned facets (status, scenario, timing, progress). However, 'the window' is undefined jargon, and it does not distinguish itself from close siblings like lesson_open, lesson_progress, or lesson_create.

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?

There is no statement of when to use this tool versus lesson_open, lesson_progress, or lessons. The agent must infer usage purely from the name and the ambiguous phrase 'for the window'.

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?

Goes well past annotations by disclosing the quota consumption rules (Free 3, Pro 10, shared with the lecture of the day), the refusal condition and how to test it, and the return contract {id, next_left} including the null-means-unlimited case. These details are consistent with the non-idempotent, non-destructive, non-readOnly annotations — each call consumes quota, which is exactly what idempotentHint=false implies.

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?

Front-loads 'Opens the next ready course lecture' and then packs limits, preconditions, and return shape into a few dense lines with no filler. The telegraphic parenthetical '(lessons() returns unfinished)' and the terse 'Daily limit: Free 3, Pro 10' read more like notes than prose and cost a little readability.

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?

There is no output schema, and the description compensates by spelling out the returned fields and the meaning of next_left. The remaining gap is the workflow ambiguity — whether the caller must invoke lesson_open on the returned id to finish the action is implied but never stated outright.

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 tool takes no parameters, so there is nothing for the description to disambiguate at the argument level. Baseline applies, with a small deduction only because the trailing lesson_open(id) reference hints at an id flowing through the workflow without saying where it comes from.

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

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

States a specific verb and resource: it opens the next ready course lecture of the active profile and adds it to the lesson pool, which separates it from lesson_open (id-based) and lesson_create. However, the closing 'Then lesson_open(id)' sits awkwardly against the opening 'Opens the next ready course lecture', leaving mild ambiguity about whether this tool actually opens the lecture or only allocates it for a follow-up lesson_open call.

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 a concrete precondition — refused while an opened lecture is not finished, with lessons() named as the way to check — plus the daily quota rules for Free and Pro. It also describes the intended follow-up workflow (lesson_open(id)), but never names an alternative tool for a different use case beyond that single hook.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds non-obvious behavior beyond them: the wait screen when the lesson is still being built and the automatic start when ready, plus the 'no microphone' constraint distinguishing it from interactive audio tools.

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, front-loaded with the action, then the timing/behavioral nuance. 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?

For a single-parameter opener with annotations covering safety and no output schema, the description supplies everything an agent needs: what happens visually, the interaction constraint, and the sequencing with lesson_create. Nothing material 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 is one required parameter, lesson_id, and schema description coverage is 0%, so nothing documents its format or expected value. The name and schema title 'Lesson Id' are largely self-explanatory, but the description contributes no additional meaning such as where an id comes from (e.g. lesson_create or lessons).

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

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

States a concrete verb+resource ('Open a lesson in a player window in the chat') and scopes the modality (audio, slides, subtitles; no microphone), which separates it from dialogue_* tools and open_in_browser. It does not explicitly name a confusing sibling like lesson_get or lesson_audio, so differentiation is implicit rather than spelled out.

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 real when-to-use context: 'Can be called right after lesson_create' and explains the wait-screen behavior while the lesson builds. No when-not-to-use or explicit alternative routing, so it stops short of a full 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 disclose the safety profile (readOnly false, non-idempotent, non-destructive), lowering the bar. The description adds one genuinely useful behavioral detail for a non-idempotent write — slides_hidden_s is a running total, not an increment. However, it never says whether a call overwrites prior progress or merges it, and the dangling 'Completed from 95 %' is unexplained.

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?

It is short, but it is a single run-on construction of colon-and-comma fragments with no front-loaded statement of purpose. The trailing 'Completed from 95 %' fragment dangles without context and does not earn its place as written.

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 four-parameter write tool with no output schema and no schema descriptions, the parameter coverage is decent, but the description omits any statement of what the call changes, whether it is safe to repeat, and what (if anything) is returned. It is adequate but leaves real gaps for a mutation tool.

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

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

With 0% schema description coverage, the description carries the full burden and mostly does: it gives units for position_s (seconds), enumerates mode as listen/watch/read, and clarifies slides_hidden_s as a total. Only lesson_id is undocumented, and that is self-evident from its name.

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 conveys what data the tool captures ('Where the user stopped') but never states the action verb (save/report/record), so the purpose is only implied. It also fails to distinguish itself from close siblings like lesson_get, lesson_open, and progress. Reads more like field documentation than a statement of what the tool does.

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

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

There is no when-to-use guidance at all: nothing says whether this should be called during playback, on pause, on exit, or how it relates to lesson_open/lesson_get/progress. The agent must infer the trigger condition from the name alone.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered without the description. The description adds genuinely useful behavior in the form of the 'newest first' ordering, the per-topic ready_undone aggregate, and the implicit filtering role of the parameters, but says nothing about pagination, empty results, or what 'active profile' means operationally.

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?

It is a single dense sentence with the scoping information ('active profile, newest first') front-loaded and no filler. The long parenthetical field dump is information-dense rather than padded, though it reads as a schema restatement in prose form.

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 no output schema, the description correctly carries the return-shape burden and does enumerate the fields returned, which is the right instinct. But it omits how the two filters behave and gives no usage context against a large sibling set, leaving an agent unable to predict results for a filtered call.

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% for both parameters, so the description must compensate and it only partly does: it enumerates the status values (building, ready, failed + error), which is real added meaning for the 'status' filter. However, the 'topic' parameter's matching semantics (exact, prefix, case sensitivity) are never addressed, and neither filter's default-empty-string behavior is explained.

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 conveys that this surfaces the lesson pool of the active profile ordered newest first, but it never states a verb such as 'list' or 'return' — the title 'List lessons' carries that load, not the description. The field enumeration implies a listing, yet nothing distinguishes this from siblings like lesson_get, progress, plan, or topics.

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?

There is no guidance on when to call this versus lesson_get, lesson_progress, plan, or topics, and no mention of whether topic/status filters are optional or what happens when omitted (defaults are empty strings). Usage must be inferred entirely from the name and 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?

Goes well beyond the annotations (destructive/idempotent hints) by disclosing the temporal effect ('counts as known for about a month'), the concrete follow-up behavior ('quizzes of that type skip the word and check it once in about three weeks'), the terminal state ('all five make the word "known" and it leaves review'), and the reversal path ('can be removed in the word card in the app'). This is exactly the extra context the annotations cannot convey.

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

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

Appropriately sized for a tool with this much implicit behavior, and the core action is front-loaded before the skill/effect details. The skill enumeration with nested parentheticals ('recognize (understands: translates from the language being learned)') is dense and slightly hard to parse, but 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?

There is no output schema, and the description still covers purpose, per-skill semantics, duration, side effects on quizzes/review, removal, and the key sibling distinction. Edge behavior (combining terms and card_ids, exact return) is left implicit, which keeps it just short of 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?

With 0% schema description coverage the description carries the param burden and does so well: it enumerates all five valid skills with parenthetical meanings, states that empty means all five, defines terms as vocabulary phrases with a shared 200-item cap, and labels card_ids as cards. It doesn't specify formats/ID shapes, so it is strong but not exhaustive.

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 action on a specific resource: marking phrases the user already knows as 'known'. It also explicitly differentiates itself from the sibling skip_card ('Not the same as skip_card, don't learn at all'), so an agent can pick the right tool without opening either schema.

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 a clear when-not via the skip_card contrast and explains the per-skill consequences that select it (e.g. 'use means the word will not become a conversation target'). It does not discuss other alternatives such as defer_card or srs_review, so it stops short of full when/when-not coverage.

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, destructiveHint=false and closed-world, so safety is covered. The description adds genuinely new context: the 2000-character cap, the active-language scoping, and the empty-if-none return condition, which no annotation conveys.

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

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

A single sentence that front-loads the resource, then packs scope, contents, size limit and edge case into one parenthetical clause with 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?

With no output schema, the description adequately characterizes the return value: free-form text up to 2000 characters or empty. The only residual gap is any format/structure of the returned notes, which is minor for a zero-parameter read tool.

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

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

The tool takes zero parameters (schema coverage 100%), so there is nothing for the description to compensate for; baseline 4 applies.

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

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

States a specific resource (the learner's standing notes for the tutor) and its scope (active language) with concrete contents listed: how to explain, what to correct, agreements, dates. The read-only nature is implicit and the write counterpart notes_set is not named, so sibling differentiation is left to inference.

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

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

Usage is implied by the resource description but never stated: there is no 'use this before a lesson/dialogue' guidance and no pointer to notes_set for updating the same content. The agent must infer both the trigger and the alternative from the name alone.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds non-redundant behavior: it replaces rather than merges, the 2000-character cap, and that an empty string clears the notes. These are exactly the operational details annotations cannot express, though return/error behavior past the cap is 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?

A single dense sentence, front-loaded with the verb and resource, with constraints parenthesized. 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 one-parameter setter with annotations covering the safety profile and no output schema, the description covers scope, mutation semantics, and the size limit. The only gap is failure behavior (e.g., text exceeding 2000 characters).

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 for the single `text` parameter, and it does: an upper bound of 2000 characters and the special 'empty clears them' semantics. This meaningfully compensates for the bare schema, though it doesn't say what happens on overflow.

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 (Replace) and resource (the learner's notes for the tutor in the active language), plus the scope qualifier 'active language'. The 'Replace' framing makes clear this is the write counterpart to the read-only `notes` sibling 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?

There is no explicit when-to-use or when-not guidance, and no mention of alternatives such as the `notes` sibling for reading. Usage is only inferable from the verb 'Replace'.

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?

Rich disclosure beyond the annotations: single-use link, 10-minute expiry, new link cancelling the previous unused one, and an explicit list of what the browser session cannot do (connection codes, account linking, sign-in changes, subscription payments). This adds real constraints an agent could not infer from destructiveHint/readOnlyHint alone.

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?

Front-loaded with the core purpose and the parameter semantics immediately after, with no filler sentences. It is dense and slightly run-on, which would benefit from clearer separation between the purpose explanation and the link-constraint list.

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 no output schema and 0% schema coverage, the description supplies the parameter meaning, the security/expiry semantics, and the sibling-purpose mapping. It omits only the concrete return (the link/URL itself) and exact purpose value formatting, which are minor gaps for this tool.

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

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

Schema description coverage is 0%, so the description carries the load and largely succeeds: it enumerates valid purpose values and explains the target keys ({card_id}, {quiz_session}, {dialogue}, {lesson}) plus the fallback when target is another user's or missing. It stops short of giving exact string casing or the target key syntax the schema's anyOf requires.

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+resource: generating a one-time sign-in link and opening a Talkfirst screen in the browser, enumerated by purpose (practice, quiz, talk, lesson, progress). It is unambiguous, though it does not explicitly contrast itself with siblings like lesson_open or dialogue_start.

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

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

Usage is implied rather than stated: the reader infers this is the browser-handoff tool, and the constraint list (works once, 10 minutes) tells them when NOT to rely on it as a durable link. There is no explicit 'use this instead of X when Y' routing, so it stays at adequate-but-implicit.

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

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

Annotations already establish that this is a read-only, idempotent operation. The description adds useful behavioral detail about the returned weeks, including that fact values are null for future weeks and that targets contain specific counters.

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

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

The description is front-loaded with the key purpose and then provides compact structural details. It is dense but every clause contributes to understanding the returned data.

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 no output schema, the description carries the burden of explaining return values and does so by describing the week structure and future-week null behavior. The reference to pace 'as in today()' is slightly indirect but overall sufficient for a no-parameter read-only tool.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Per the baseline for parameterless tools, this dimension scores 4.

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

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

The description clearly states that this tool provides the weekly study plan of the active language and outlines the returned week structure. It is specific about the resource but does not explicitly distinguish itself from the sibling plan_set 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 does not state when to use this tool versus alternatives such as plan_set. Usage is only implied by the tool's purpose, with no explicit context or 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 declare destructiveHint=true and idempotentHint=true; the description adds the crucial scope of destruction ('from the current week on', 'past weeks stay unchanged'), which is not in the annotations. It does not disclose auth/permission requirements, but the destructive boundary is well communicated.

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 action and scope are front-loaded, and every clause carries information (dates, limits, ranges). It is dense and slightly run-on but free of filler.

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

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

For a destructive, no-output-schema mutation tool, the description supplies the replacement scope, constraints, and return reference ('as plan() does'). This is close to sufficient; only auth/permission context is missing.

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

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

Schema coverage is 0% and the nested object is opaque, so the description carries the full burden and largely delivers: it names the 'weeks' array and its fields (start, focus, targets), the date format, and numeric ranges for each target. It does not explain optionality or unknown-field handling.

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 verb 'Replace' and resource 'plan' are specific, and 'from the current week on' scopes it precisely. It implicitly distinguishes itself from the sibling plan() by wording the return as 'as plan() does', but does not explicitly frame plan() as the read counterpart.

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?

'Replace the plan from the current week on' plus 'Past weeks stay unchanged' tells the agent the exact effect and boundary. It stops short of an explicit when-to-use vs. plan() routing statement, but the 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?

Annotations already declare the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description adds real behavioral context the annotations do not: a recording widget is involved, and recall mode changes what the widget renders (translation only, user speaks from memory). It omits whether the deck position advances permanently and what the result looks like, keeping it at a solid 3.

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

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

One dense paragraph, front-loaded with the core action, then the three argument modes. Every clause carries information; the semicolon-separated fragments are terse but readable. Slightly run-on phrasing ('No arguments: the next phrase from the deck') costs a point.

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?

There is no output schema and no schema description coverage, so the description carries the burden, and it covers modes and the recall precondition adequately. However, for a tool with 3 undocumented parameters and a sibling assess_attempt, it says nothing about the return value, whether an attempt is recorded afterward, or how the recording flow completes.

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 carry the parameters, and it does: it explains text ('any phrase'), card_id ('a specific card'), and recall ('recall mode... needs a card'), plus the default no-argument behavior that the schema's empty-string/default values do not convey. It does not say what happens if text and card_id are supplied together, which prevents a 5.

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

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

States a concrete verb+resource ('Show a phrase for pronunciation practice') and names the mechanism ('recording widget'), so the agent knows exactly what the tool does. It does not explicitly differentiate itself from audio-related siblings such as reference_audio or quiz_audio, so it stops short of a 5.

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 lays out the three invocation modes clearly (no arguments = next deck phrase, card_id = specific card, text = arbitrary phrase) and gives a precondition ('recall... needs a card'). It offers no exclusion guidance or comparison against alternative practice/quiz tools, so it is clear context without 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 establish readOnly/idempotent/non-destructive, so the description correctly does not contradict them. It adds real value beyond the structured fields by decoding the semantics of the payload: level is self-assessed A1-C2, mode is strict/zen/mix chosen per session, advance is a delay in seconds with 0 meaning manual, and pace lives in today() rather than here.

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?

It is one long run-on paragraph stitched together with semicolons, and nested details such as the purpose variants and the advance units are buried mid-sentence. Every clause carries information, but the flat formatting makes it slower to parse than a bulleted field list would be.

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 no output schema and no parameters, the description carries the full burden of describing the return shape, and it does so field by field, which is exactly what an agent needs. The remaining gap is edge behavior: what is returned when no active language profile exists is not stated.

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 tool takes zero parameters, so there is nothing for the description to disambiguate on the input side. The field glossary it does provide is orthogonal to the (empty) schema rather than redundant with it.

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 the resource precisely (the learner's profile in the active language) and even enumerates its fields, so an agent understands it is retrieving the profile object. But it never uses a verb like 'get'/'return' and never mentions profile_update, so the read-vs-write distinction from its closest sibling is left implicit.

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 no guidance on when to call this versus profile_update, today, progress or plan, all of which touch adjacent data. There are no exclusions, prerequisites, or timing hints; the agent is left to infer usage entirely from the resource name.

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

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

The description adds a genuinely non-obvious side effect: setting `level` or `target_level` resets `goal_set_at` and zeroes the pace estimate. That goes well beyond the annotations. It still doesn't explain why destructiveHint=true beyond that reset, nor whether omitted fields are preserved (merge vs replace) or how the patched values are validated.

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 sentences, front-loaded with the action and followed by the important side effect. The parenthetical field list is long but each item maps to a patch key, so it earns its space.

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?

No output schema exists, yet the description tells the agent exactly what is returned (the profile plus its field list) and discloses the one destructive consequence. Only patch merge semantics and validation rules are missing, which is a modest gap for a mutation 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 coverage is 0% and `patch` is a free-form object with additionalProperties, so the description carries the burden — and it does, enumerating all eleven patch keys (level, purpose, about, mode, goals, deadline, target_level, advance, new_per_day, speed_ru, speed_lang). It also defers value formats to profile(), which is a practical pointer. Types and allowed values (e.g. for `mode` or level scale) remain undocumented, so not a 5.

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

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

States a specific verb and resource ('Change fields of the learner's profile in the active language') and names the field set that can be changed. The verb 'change' plus the return value implicitly separates it from the read-only sibling `profile`, but that contrast is never made explicit.

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

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

Usage is only implied: a reader infers you should call `profile` first to learn the field formats and call this only when mutating. There is no explicit when-to-use / when-not statement and no prerequisites (e.g. must a profile exist, must a language be active).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety needs no restating. The description adds real behavioral value by enumerating the returned content categories and capping topics at 6 (up to 6 deck topics plus no_topic), which the annotations cannot convey.

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

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

The main purpose is front-loaded and there is no filler, but the phrasing is garbled ('over days days', 'most words in work') and reads as a compressed field dump, forcing the agent to reparse rather than understand immediately.

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 no output schema, the description must describe returns, and it does list the main sections. However, the cryptic topic field names (added, in_work, learned) and the broken day-window phrasing leave an agent uncertain about the exact response shape for a stats tool with several output sections.

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?

One parameter (days, default 14) with 0% schema description coverage, so the description carries the burden. It references the day window ('over days days') but adds no units, bounds, or clarification on whether the window includes today, leaving the parameter only partially explained.

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

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

The description states a specific verb+resource: a learning-progress summary over a day window, listing cards, reviews, activity by source, recent pronunciation attempts, and topic breakdowns. An agent can tell this is a statistics/digest tool, though it never explicitly contrasts itself with sibling stats tools such as word_stats, lesson_progress, or today.

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?

There is no explicit when-to-use or when-not-to-use guidance. The 'over days days' phrasing implies a rolling window, but nothing indicates which sibling to pick when an agent needs per-word stats (word_stats) or lesson-specific progress (lesson_progress).

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds one genuinely useful behavioral fact — that the record is written once — which corroborates idempotentHint=false and tells the agent not to retry or expect overwrite. It says nothing about failure behavior or whether session_id must already exist, so it is additive but thin.

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

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

A single sentence, front-loaded with the core meaning and using a parenthetical for units/range — no filler. It is arguably compressed to the point of omitting needed usage context, but as structure it is clean.

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 four-parameter telemetry write with no output schema and no annotations about returns, the description covers the metric itself but leaves idx/session_id undefined and never states the call ordering (after quiz_answer) or whether duplicate writes are rejected. Adequate minimum, 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?

Schema coverage is 0%, so the description carries the burden, and it does explain two of four parameters: after_ms units and bounds (0...3,600,000) and the meaning of auto (auto-advance moved on). session_id and idx get no explanation at all, so the compensation is only partial.

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

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

The description states exactly what value is being recorded: dwell time on a question after answering, in ms, with the auto-advance flag meaning. That is a specific resource+measurement, not a tautology of the name. It does not, however, tie itself to the sibling it follows (quiz_answer) or distinguish itself from quiz_save/telemetry, so it stops short of a 5.

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?

There is no explicit when-to-use statement, no ordering hint relative to quiz_answer, and no exclusion of alternatives. The only usage signal is the trailing 'Written once', which the agent must interpret on its own.

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 declare destructiveHint=true and non-idempotent, so an agent knows this mutates state, but the description never warns about that or says what gets altered/overwritten, nor whether an answer can be re-submitted. It does add useful behavioral facts (answer_ms outside 0...3,600,000 is not saved), which lifts it above a 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?

It is compact with little redundant filler, but it is one dense run-on sentence with no front-loading of the parameter glossary, making it hard to parse quickly. Structure is weak even though the content 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 10-parameter, annotated, no-output-schema tool, the description covers most parameters adequately, but omits the two required ones (session_id, idx) and gives no account of what happens on success or the destructive consequence flagged in 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 coverage is 0% with 10 parameters, so the description carries the burden and does explain nearly all of them (choice, correct, attempt_id, hide, hint, skills, exact, answer_ms). Only idx and session_id are left undefined, and the explanations are terse ('hide is defer, skip or known') but directionally useful.

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?

Opens with a specific verb+resource ('Answer a quiz question') that clearly distinguishes it from quiz_start, quiz_end, quiz_history, and quiz_result. The remainder elaborates parameters rather than the purpose, but the core act is unambiguous.

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

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

There is no explicit when-to-use/when-not guidance versus siblings like quiz_after, quiz_result, or assess_attempt beyond the passing mention that attempt_id is 'the assess_attempt attempt for say it aloud'. An agent must infer the workflow context on its own.

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 (readOnlyHint=false, idempotentHint=false), the description discloses materially important behavior the agent could not otherwise know: that the call generates audio and can charge, and the exact shape of the not-cached response (cached: false, no b64, no generation). This is useful side-effect and billing context.

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?

It is short, but the middle sentence ('In "Reverse" and "Say it in <language>" only after answering: the right answer, or with option the option with this number') is grammatically tangled and hard to parse, and the quoted mode names are ambiguous without more context.

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?

There is no output schema, and the description does cover the return format and the caching/billing trade-off, which is good. But with 4 parameters, 0% schema coverage, and no explanation of session_id/idx or the prerequisite quiz state, an agent still lacks enough to invoke this confidently.

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 load. It explains two of four parameters meaningfully (option = the answer option with this number, cached_only = only ready audio with no fallback), but idx and session_id are left completely unexplained, so half the parameters remain opaque.

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?

It states a specific resource and return format: the audio of the question phrase in the target language as base64 mp3. The scope is clearly tied to quiz questions, but it never distinguishes itself from sibling audio tools like reference_audio, dialogue_audio, or lesson_audio, so the agent gets no routing help beyond the name.

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 conditional usage note for 'Reverse' and 'Say it in <language>' modes (only after answering) and explains what cached_only does. However, it never says when to prefer this over the other audio siblings or what session/quiz state is required, leaving usage largely inferred.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by stating what survives the deletion ('quiz sessions and answers stay'), which is the key behavioral question for a destructive call. It stops short of saying whether the delete is reversible or how dependent records are handled.

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 short sentence with the action front-loaded and the scope caveat immediately after it. Nothing is wasted or buried.

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-parameter destructive delete with no output schema, the essentials are mostly present: the action, the identifier, and what is preserved. However, it omits how to find a valid quiz_id and whether the operation can be undone, which leaves gaps for an agent about to perform an irreversible write.

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 says nothing about quiz_id — not its format, not where to obtain it (e.g., from the quizzes or quiz_history tools). With one undocumented parameter, the description fails to compensate for the schema gap.

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

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

The description gives a specific verb and resource ('Delete a saved quiz'), matching the name and title, and the parenthetical scopes exactly what is removed versus preserved. It does not explicitly name a sibling, but it is clearly distinguishable from quiz_save, quiz_end, and quiz_history on verb alone.

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?

There is no explicit when-to-use statement, no prerequisites, and no mention of an alternative (e.g., quiz_end vs quiz_delete). The parenthetical clarifies blast radius rather than when this tool is the right choice, leaving the agent to infer the use case.

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 destructiveHint=true and readOnlyHint=false, so the terminal/state-destroying nature is flagged structurally. The description adds only that the call returns the result; it does not say what is destroyed, whether an in-progress session is invalidated, or whether the result is final.

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 short sentence with the action front-loaded and zero padding. It is efficient, though it is terse to the point of under-specification.

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-parameter terminal tool with annotations covering safety and no output schema, the description is minimally adequate. It leaves the session_id semantics and the meaning of 'early' vs natural completion to inference.

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

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

Schema coverage is 0% for the single required session_id, so the schema documents nothing about it. The description does not mention session_id at all and thus fails to compensate 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?

States a specific verb+resource ('End the quiz') and adds scope ('early') plus a return ('return the result'), so it is not a bare tautology. It does not, however, distinguish clearly from siblings like quiz_result or quiz_after, which likely also surface quiz outcomes.

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?

'End the quiz early' implies the timing condition for calling this tool. It offers no explicit when-not guidance or named alternative, so an agent must infer that normal completion is handled elsewhere and that quiz_result merely reads rather than terminates.

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=true, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful semantics, notably that source=null means the quiz was picked by terms/card_ids and that origin distinguishes app from chat, but it says nothing about paging, default result size, or what happens at the limit boundary.

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

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

One front-loaded sentence that states the resource and ordering before the field list, with no filler. The dense field enumeration is long but every item conveys return-shape 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?

With no output schema, the description carries return-value burden and does so thoroughly by enumerating id, type, source, tag, mode, score/total, size, origin and timestamps. However, it omits the limit parameter's behavior, leaving a gap for a listing tool that returns a bounded set.

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 single parameter limit has 0% schema description coverage and is not mentioned anywhere in the description, including no default of 10, no maximum, and no effect on ordering. With coverage at 0% the description was expected to compensate and it does not address the parameter at all.

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 clear resource (recent quizzes) scoped to the active profile with an explicit ordering (newest first), which an agent can act on. It does not differentiate itself from related siblings such as quizzes or quiz_result, so the boundary must be inferred from the name.

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 when-to-use guidance, no mention of when-not to use it, and never names an alternative like quizzes or quiz_result. The agent must guess that 'recent' listing is the distinguishing purpose.

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 true, so the safety profile is covered. The description adds real value by detailing the returned field structure (questions, detail object, answer_ms/after_ms/after_auto), but says nothing about auth, error behavior, or session-state requirements.

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?

It is front-loaded with a 'Quiz details:' label and remains a single paragraph, but is a dense run-on of nested field names with no purpose sentence. The field detail is largely justified because no output schema exists, but it could be structured more cleanly.

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 no output schema, the description reasonably documents the return shape, which is its main contribution. However, it omits the operational purpose and parameter meaning, so an agent still lacks enough to confidently select and invoke it over sibling quiz tools.

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 single parameter session_id is never mentioned in the description, and schema description coverage is 0%, so nothing compensates for the gap. The parameter is only inferable from its self-explanatory name.

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 the resource (quiz result) and enumerates its contents, but never states an action verb like 'retrieve' or 'get'. It reads as output documentation rather than a purpose statement, and gives no basis for distinguishing it from siblings such as quiz_history or quiz_after.

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?

There is no guidance on when to call this versus quiz_history, quiz_end, or quiz_after, and no stated preconditions (e.g. that a session must exist or be completed). The agent must infer usage entirely from the name.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds real behavioral detail: the 80-character name cap and that card_ids are persisted as their phrases. It does not say whether saving a duplicate name overwrites, whether saved quizzes consume storage limits, or whether the underlying cards/SRS state is untouched.

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

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

Two sentences, front-loaded with the purpose before the parameter notes, and no filler. The 'spec:'/'name:' label style is terse to the point of being slightly cryptic, but nothing is wasted.

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 2-param mutation with a nested object and no output schema, the description covers inputs well but not outputs – it implies an id exists (used as saved=id) yet never says the saved quiz's identifier is returned, nor what happens on a name collision or an invalid spec field.

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 spec is an opaque nested object with additionalProperties, so the description must carry the load – and it does, enumerating the accepted fields (type, source, size, mode, tag, terms, card_ids), the phrase-storage rule for card_ids, and the name length limit. It still omits value domains for type/source/mode, so it is strong but not complete.

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

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

States a specific verb and resource ('Save a quiz') plus scope ('of the active language') and immediately ties it to the sibling that consumes it, 'quiz_start(saved=id)'. An agent can distinguish this from quiz_start, quiz_delete, and quizzes without opening any schema.

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?

Explains the intended lifecycle – save now so the quiz can be re-run later via quiz_start(saved=id) – which is genuine when-to-use guidance and names the alternative path. It stops short of saying when *not* to save (e.g., one-off quizzes) or how it relates to quiz_delete.

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?

Goes well past the annotations by disclosing the destructive side-effect in concrete terms: "One quiz per profile: a new one closes an unfinished one," consistent with destructiveHint=true. It also explains placement's side effects on card status (right promotes to known and leaves review, wrong stays in learning) and describes per-phrase result fields including score, reaction_ms and suggest_known.

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 lead sentence and the no-argument default are properly front-loaded, and length is defensible for 11 undocumented parameters. However, the body is a single dense prose block with heavy nested parentheticals, which makes the per-parameter rules hard to scan; a short structured list would carry the same content far more legibly.

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 no output schema and no parameter descriptions in the schema, the description still covers modes, defaults, result shape ("known N, to learn M", per-phrase fields), and edge cases such as one-quiz-per-profile. An agent has everything needed to call it correctly on the first attempt.

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% across 11 parameters, so the description carries the full burden and does: it enumerates the values for type, source, mode and size (1-30) that the schema does not, and explains cross-parameter interactions such as card_ids nulling source and size, and repeat_of inheriting order and type. Tag is the thinnest entry (only "topic (with tag)" and its exclusion under placement), but every parameter is addressed with meaning beyond its name.

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 concrete verb and resource ("Start a quiz in the widget") and immediately explains the zero-argument default path. It implicitly distinguishes itself from quiz_after/quiz_save/quiz_end by covering saved sessions, repeats and placement variants, though it never names a sibling explicitly.

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

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

Clear guidance on when to supply arguments versus rely on smart defaults, and which parameter selects which mode of use (terms vs card_ids, repeat_of vs saved, placement). There is no explicit exclusion such as "use quiz_after instead when...", which keeps it short of a 5.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add traits beyond that — and it does: sort order ('most recently used first') and language scoping. It stops short of noting any result cap or pagination behavior, which is a minor gap for a list tool.

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

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

A single sentence with the collection and ordering front-loaded, followed by the returned fields. It is dense but every clause carries information, particularly the field list, since no output schema exists.

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 zero parameters and no output schema, the description carries the return-value burden and does it by enumerating id, name, spec, created_by, created_at, used_at and uses. Only ambiguity in the meaning of 'spec' and any implicit result limit are left unaddressed.

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

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

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Instead it usefully documents the shape of the non-parameterized call by naming the fields returned.

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 definition names the resource precisely ('Saved quizzes of the active language') and adds scope and ordering, so an agent knows exactly what collection is returned. It never routes to a sibling, though — the relationship to quiz_history, quiz_save, or lessons is left for the agent to infer.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative, despite a dense sibling set of quiz_* and other list tools (lessons, notes, topics). The only usage signal is the implicit scope 'of the active language', which is context rather than guidance.

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

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

The description adds the return format ('mp3 in base64'), which is useful. However, despite annotations showing readOnlyHint=false and idempotentHint=false, it does not disclose side effects, caching, permissions, or what happens on repeated calls.

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 single sentence is front-loaded but under-specifies rather than concisely covering the necessary ground. It omits essential usage and parameter details, so brevity here is a liability.

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 no output schema, one undocumented parameter, and sparse annotations, the description should carry more burden. It mentions the mp3/base64 return format but leaves out what the tool actually does, when to use it, and how to supply the text parameter.

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 only parameter ('text') is undocumented in the schema. The description implies 'text' is a phrase, but does not explain constraints such as language, length, or expected input format.

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 restates the tool name and title ('Reference audio') and adds only 'of a phrase (mp3 in base64)'. It does not state a verb or explain whether the tool generates, retrieves, or converts audio, so the purpose remains largely tautological.

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?

There is no guidance on when to use this tool versus the many sibling audio tools such as dialogue_audio, lesson_audio, quiz_audio, or practice_phrase. The description provides no context, prerequisites, or 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the conditional semantics: hard delete (including the associated card) when there is no answer history, versus a soft 'don't learn' mark when history exists. It still does not say whether the delete is reversible or what the caller gets back.

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

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

One sentence, verb-first, with the two behavioral branches cleanly split after the colon. No filler or repetition; a touch more structure (e.g. stating the input) would be needed for a 5.

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 mutation with no output schema, the description covers the important behavioral fork but omits what the call returns, what happens on an invalid or already-removed id, and whether the deck/card structure outside the entry is affected. Annotations carry the destructive signal, so the omission is a gap rather than a failure.

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 single parameter (lexicon_id, integer) is never mentioned in the description. The name is self-explanatory, so an agent can likely supply it, but the description does not compensate for the documentation gap as the low-coverage rule requires.

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 (remove) and resource (vocabulary entry) and then spells out the two distinct outcomes, which separates it from siblings like vocab_add, mark_known, and quiz_delete. It does not explicitly name an alternative tool, so it stops short of the top mark.

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

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

Usage is only implied: the agent learns what happens in each state, not when to choose this tool over mark_known or quiz_delete. There is no statement of prerequisites, irreversibility tradeoffs, or the alternative path for entries with history.

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 declare a non-readonly, destructive, non-idempotent write, so the safety profile is covered. The description adds genuinely valuable context not present in the annotations: the report is sent to a developer and automatically includes the user's last 10 activity events (event kind, time, short summary) while explicitly excluding recordings. It does not state whether submission is irreversible or what the caller gets back, but the auto-attached telemetry disclosure is meaningful behavioral detail.

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

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

Purpose and the accepted kinds are front-loaded, and every clause carries information (enums, length limits, auto-attached events). The single semicolon-chained sentence is dense, making the parameter rules harder to parse than a short bulleted structure would be, but 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?

With no output schema, the description need not explain return values, and it does cover what gets transmitted, including the automatic activity-event attachment. For a 6-parameter write tool it is close to complete; the only real gaps are confirmation/privacy expectations and what a successful submission yields.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it supplies the enum values for 'kind' (bug/feature/idea/ux) that the schema lacks entirely, plus length limits (title ~200 chars, details up to 4000) and maps the four free-text fields. The grouping of 'details, what_tried, what_happened, expected' into one clause leaves it slightly ambiguous whether each field or the combined text is capped at 4000, and it does not distinguish what each field is for beyond its name.

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

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

States a specific verb and resource: sending a bug report or request to the Talkfirst developer, with the accepted report kinds enumerated. No sibling tool overlaps with feedback submission, so an agent can immediately tell this is the outbound-reporting 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?

Usage is implied by the enumerated kinds (bug, feature, idea, ux) — the agent can infer it should call this when the user wants to report a defect or request something. However there is no explicit when-to-use/when-not statement, no note on whether confirmation is required before sending, and no guidance on handling user privacy concerns.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuine behavioral context beyond that: the card is not deleted but suppressed across review, quizzes, and conversations, which is the practical effect of the destructive flag. It stops short of saying whether the suppression is reversible or how to undo it, which is the one remaining gap.

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, front-loaded with the core outcome and ending with the disambiguating alternative. No filler or repetition of the name/title.

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-parameter destructive toggle, the description plus annotations cover outcome, irreversibility hint, and the sibling alternative, and no output schema exists to explain. The only omission is identifier semantics for card_id, which is minor but leaves the agent guessing at the one input it must supply.

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 single parameter (card_id) is only titled 'Card Id' with no type/format guidance. The description refers to 'the word' and 'the card' generically but never clarifies what identifier to pass. With low coverage, the description should compensate for the schema gap and does not.

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 action (skip a card, permanently) and spells out the exact consequence: the word will not appear in review, quizzes, or conversations. It also names the sibling it is distinct from (mark_known), so an agent can route between the two without opening either schema.

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 gives the selecting condition for the alternative: 'For words the user already knows there is mark_known.' That is a when-to-use-other rule, which is exactly what a routing agent needs.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered externally. The description adds nothing beyond that: no return format, no ordering, no pagination/limit behavior, no session context requirements.

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?

It is short, but brevity here reflects under-specification rather than conciseness — the single sentence carries no information the agent does not already have from the title. Nothing is front-loaded because there is nothing substantive to front-load.

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

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

This is a simple read-only list tool with one optional parameter and no output schema, so it does not need much, but it should at least describe what a 'due' card looks like and how the limit applies. As written, the description leaves the agent without enough to invoke it confidently versus srs_review.

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% for the single 'limit' parameter, which has only a default of 10 and no explanation. The description does not compensate by stating what limit caps, whether it is a maximum, or what happens when it is omitted.

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 is a verbatim restatement of the title 'Cards due for review' and the name srs_due, with no distinct verb (e.g., 'list'/'return') and no differentiation from siblings such as srs_review, defer_card, or skip_card. It nominally identifies the resource concept, but it is effectively a tautology.

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?

There is no when-to-use guidance, no mention of alternatives despite several closely related siblings (srs_review, defer_card, skip_card, mark_known), and no stated prerequisites. The agent must infer the usage context entirely from the name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered and the description's 'record' verb is consistent with it. The description adds the grade-scale semantics but says nothing about side effects such as rescheduling the card, updating due dates, or whether repeated reviews stack — meaningful context for a non-idempotent write.

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

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

A single sentence that front-loads the action and then enumerates the grade scale inline. No filler, no redundancy, and the most decision-relevant detail (the grade values) is present immediately.

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 mutation with no output schema, the description covers the critical grade scale but leaves real gaps: it never explains what recording a review does to the card's schedule or how it relates to srs_due. Adequate to invoke, but not complete for an SRS mutation.

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

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

Schema coverage is 0%, so the description must carry the load. It fully documents the grade parameter's four values, which the schema leaves as a bare integer with no enum, adding genuine value. However, card_id is entirely undocumented in both the schema and the description, so compensation is only partial.

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

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

States a specific verb and resource ('Record a card answer') and immediately defines the grade scale, so an agent knows exactly what the tool does. It does not explicitly distinguish itself from adjacent siblings like skip_card, defer_card, or mark_known, which is the only thing keeping it out of 5 territory.

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

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

Usage is implied: you call this after the learner attempts a card and you supply the recall grade. There is no explicit statement of when NOT to use it or which sibling to reach for instead (skip_card, defer_card, mark_known), so the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a non-idempotent, non-destructive write. The description adds almost nothing beyond that - no mention of batching, auth, rate limits, or what happens to submitted events, though 'call results' hints that outcomes are reported.

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?

It is a single short line with the key noun front-loaded, so it is not bloated. However, it is composed of cryptic colon-delimited fragments rather than a readable statement, which reduces its usefulness per word.

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 write-side tool with one required parameter, no output schema, and 0% schema coverage, the description should explain what an event must contain and when the widget should emit telemetry. It instead provides an incomplete, ambiguous field sketch, leaving the caller without enough information to invoke it confidently.

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 single events parameter is a free-form array (additionalProperties: true) with no item schema, so the description is the only source of the event object's keys ({type, window, host, load, ...}). It partially compensates by listing likely fields, but the trailing ellipsis and lack of required/optional distinction leave the shape ambiguous.

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 phrase 'Window telemetry: events [{type, window, host, load, ...}]' names a resource (window telemetry events) and hints at their shape, but no clear verb is stated and the syntax is telegraphic. It gives an agent some idea of what is being sent but does not clearly distinguish this from siblings like report_feedback.

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

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

There is no when-to-use guidance, no preconditions, and no mention of alternatives or when not to call it. The agent is left to infer that this is the widget-side telemetry submission endpoint purely from the name.

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/non-destructive, so the safety profile is settled. The description adds genuine behavioral context beyond that: the pauses_summary aggregation window (over 14 days) and the null return of last_quiz when no quiz exists. It stops short of stating freshness or cost.

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?

Front-loaded with 'Today's summary' and then a long semicolon-chained field list. No sentence is strictly wasted, but the run-on form and opaque referential syntax such as docs("pace") and lessons() hurt scanability.

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?

There is no output schema, so the description carries the full return-value burden and does so comprehensively, enumerating every field. Remaining gaps are the cryptic internal references (docs("pace"), lessons()) whose meaning an agent can only guess.

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 tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 makes clear this is a read-only daily snapshot aggregating cards due, streak, targets, quiz, pace, and ready lessons. The resource is unambiguous, though there is no explicit verb and no differentiation from siblings like progress or profile, which also expose learner state.

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

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

No statement of when to call this versus progress, profile, srs_due, or quizzes, and no prerequisites or exclusions. The agent must infer from the name alone that this is the 'everything-at-a-glance' entry point.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by explaining field semantics that matter for behavior ('current is the topic new cards come from', 'tags lists all card tags of the user, own ones included'), which the annotations cannot convey.

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

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

The content is front-loaded with the resource and level scoping, but the definition is a single sprawling semicolon-chained sentence mixing return fields, field semantics, and cross-tool hints. Every clause is informative, yet the structure is dense and harder to parse than necessary.

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

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

With no input parameters and no output schema, the description carries the full burden of describing the return shape, and it does list the key fields (id, title, tag, cards, added, in_work, learned, current, tags). It is complete enough to call and interpret, though it omits nested structure or ordering details.

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 tool takes zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to clarify about inputs, and schema coverage is 100% by virtue of being empty.

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 identifies the resource (deck topics of the active language, grouped by level) and enumerates the returned fields, and it names downstream consumers (vocab_list, quiz_start source=topic), which helps separate it from siblings. It lacks an explicit verb like 'list', so purpose is clear but not perfectly stated.

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

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

Usage is only implied: the mention that 'tag' is used for vocab_list and quiz_start source=topic hints at how the output feeds other tools, but there is no explicit when-to-use or when-not-to-use guidance versus siblings like progress, today, or word_stats.

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?

Discloses real behavioral traits beyond the annotations: 'No duplicates are created', the automatic kind inference rule, and the entry-form rule (dictionary form in the entry, spoken form in example). It does not say what the call returns or whether existing entries are reported back, which the absence of an output schema makes more relevant.

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?

Front-loads the action and the item shape, and every sentence carries rule content. The single sentence-chain after the JSON example is dense and slightly hard to parse on a first read, but nothing is padding.

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-parameter mutation with no output schema, the description covers the field contract, dedup behavior and entry rules well. It stops short of the result shape (created vs skipped) and any permission/auth note, which would close the remaining 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 coverage is 0% and the items array is untyped (additionalProperties: true), so the description carries the full contract: it enumerates term, meaning (with ui_lang sourcing), example, level (A1..C2) and kind (chunk|formulation), plus the fallback rule when kind is omitted. This is exactly the compensation a low-coverage schema requires.

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+resource ('Add words and phrases to the vocabulary and to cards') and explains the entry model in detail. It never names the near siblings add_chunk / add_cards, so an agent must still infer which tool to pick when a single chunk is the target.

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 implicit structural guidance (chunk vs formulation, the >5-word default rule, and a pointer to docs("vocab") for entry rules) but no explicit when-to-use / when-not-to-use guidance relative to add_chunk, add_cards or mark_known.

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/non-destructive, so the bar is lower, and the description adds real value: deterministic 'oldest first' ordering, pagination bounds, and the meaning of returned fields (skills levels and held_days) is spelled out. It does not discuss rate limits or auth, but for a read-only list tool this is solid added context.

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?

It is front-loaded with purpose before parameters, and every clause carries information, but the entire body is one semicolon-chained run-on sentence that is hard to scan. Dense and non-redundant, yet poorly structured for comprehension.

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 no output schema and six parameters, the description does what it should: it defines filters and also explains return-side concepts (total, skills levels, held_days). A clearer statement of the default page size behaviour and offset semantics would close the remaining 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 coverage is 0%, so the description must carry the full load, and it does: limit range (1-100), offset, status enum values, kind enum values with parenthetical meanings, tag format including the 'topic:<id>' convention, and the exact shape/semantics of skill_below. This is essentially complete parameter documentation embedded in prose.

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 opening clause states a specific verb and resource (list the user's vocabulary), plus ordering ('oldest first') and pagination semantics ('a page of limit entries (1-100) from offset'). It is unambiguous what the tool returns, though it never names a sibling (e.g. word_stats, vocab_add) to differentiate itself explicitly.

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

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

There is no when-to-use guidance, no comparison against alternatives like word_stats or topics, and no stated prerequisites or exclusions. The only cross-reference ('see topics()') explains tag syntax, not tool selection, so usage must be inferred.

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, non-destructive, closed-world, so the safety profile is covered. The description goes well beyond that by defining 'away' (>30 s), the groups buckets (<=1/<=3/<=5/<=10/<=20 s and '20+'), and how the server uses median time to distinguish quick from slow answers — genuinely useful semantics for interpreting results.

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 content is dense but front-loaded: the field inventory comes first, followed by definitions of the trickier fields. Nearly every clause earns its place, though the closing sentence on review-interval mechanics is more internals than an agent strictly needs.

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 no output schema, the description must describe the return shape, and it does so thoroughly, naming each top-level field and the structure of times[skill]. For a single-parameter read-only tool this covers what an agent needs to call and interpret 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?

There is one parameter (term) with 0% schema description coverage, so the description must carry meaning. It implies term is the vocabulary word being queried, which is adequate but adds no syntax, case-sensitivity, or lookup-failure guidance beyond that inference.

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 gives a specific verb (returns statistics) for a specific resource (a vocabulary word) and enumerates the returned content: status, skills levels, known marks, and quiz answer times. It is clearly distinguishable from generic siblings like progress or profile, though it never names a sibling explicitly to route against.

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?

There is no statement of when to reach for word_stats versus progress, quiz_history, or vocab_list. The only framing sentence, 'For discussion only', comments on how the server interprets timing data rather than when to call the tool.

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