English Test Coach

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description adds genuinely new behavioral facts: execution is local and nothing is saved or sent to an AI, and the output is counts rather than a score. That privacy and output-scope context goes beyond the structured fields, though permissions or limits are not discussed.

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

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

Three short sentences, each carrying distinct information: what is counted, the local/no-AI execution guarantee, and the not-a-band-score caveat. The core action is front-loaded and there is no 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?

With no output schema, the description correctly clarifies that the output is counts and not a band score, and it discloses the local execution model. For a two-parameter tool this is nearly sufficient, losing only the input length limit and the meaning of the taskType options.

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 implies the text input ('a piece of writing') and that the task type drives the IELTS minimum ('for the task'), which gives meaning to both parameters. However it never explains the Task 1/Task 2 enum values or the 24,000-character cap, so compensation for the 0% coverage 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 a concrete verb and resource — counting words, sentences and paragraphs — plus the extra behavior of comparing against an IELTS minimum. It also actively separates itself from the sibling calculate_band_score by stating 'These counts are not a band score,' so an agent can route correctly without opening a 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?

Usage is only implied: the 'not a band score' disclaimer nudges the agent toward calculate_band_score for scoring, and the IELTS-minimum comparison hints this is a pre-submission length check. But it never states when to use this tool or names the alternative explicitly, so the routing 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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real behavioral content: the official .25/.75 rounding rule and the caveat that the Task-based Writing estimate is approximate. Flagging the estimate's lower confidence is genuinely useful disclosure beyond the structured fields.

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 with no filler; the core calculation and its rounding rule come first, and the optional Task-based path follows. Every clause carries 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?

There is no output schema, so the description should convey what comes back; it implies a resulting band but does not explicitly state the output shape or whether the estimated Writing band is returned separately. Given the tool's simplicity and the annotations, this is a minor gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it maps the four band inputs and explains that writingTask1/writingTask2 are an optional alternative path where Task 2 counts double. It aligns with the schema's required list by saying the Task inputs are optional, though it does not restate the 0-9 / 0.5-step constraints (which the schema encodes).

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?

Starts with a specific verb and resource ('Calculate the overall IELTS band') and enumerates the exact inputs (Listening, Reading, Writing, Speaking). It is unambiguous and cannot be confused with any sibling tool such as analyze_writing or search_vocabulary.

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

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

The description implies usage by explaining the required four-band input and the optional Task 1/Task 2 mode, so an agent can infer when it applies. However, it never states when to use this instead of siblings or any preconditions, leaving routing 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 readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds behavior annotations don't: the response bundles planning guidance, sample-answer links and image visuals, and it warns not to invent figures for Academic Task 1 visuals — a real output constraint.

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

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

Two tight sentences with no filler. The core action is front-loaded and the visual-figure warning is placed immediately after, where it is most likely to be read.

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, so the description carries the return-value burden and does so by naming the question, planning guidance, sample-answer links and images. It stops short of saying how to discover valid task IDs, which is 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 description coverage is 0% for the single taskId parameter, so the description is the only prose available; it says retrieval is 'by ID' but does not explain what the ID denotes or how to choose one. The enum values are self-describing topic slugs, which partly compensates.

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: retrieve one original practice question by ID, and enumerates what comes with it (planning guidance, annotated sample-answer links, image visuals for Academic Task 1). This distinguishes it from search_practice (finding tasks) and get_sample_answer (returning an answer).

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

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

Usage is only implied: the mention of 'links to any annotated sample answers' hints that the answers themselves come from get_sample_answer, and the single-ID retrieval contrasts with search_practice. No explicit when-to-use or when-not statement 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return content (paragraph notes, vocabulary) and a meaningful caveat that these are illustrative, not officially scored scripts. It does not cover error behavior for an invalid sampleId.

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: the core action first, then the clarifying caveat. Every clause earns its place and nothing is redundant.

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 payload, and it does (annotated sample with paragraph notes and vocabulary). Combined with the ID provenance and the scoring caveat, an agent has everything needed to call this 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 coverage is 0% and the single parameter is an opaque enum of long slugs, so the description carries the burden. It does so by explaining the ID's origin ('from get_practice_task'), which is the key semantic the schema lacks; the enum values themselves are largely self-descriptive.

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 ('Read one original annotated sample answer by ID') and names the payload (paragraph notes, useful vocabulary). It is clearly distinct from siblings like get_practice_task, analyze_writing, and calculate_band_score.

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 provenance guidance — the ID comes 'from get_practice_task' — and a scope caveat that samples 'are not officially scored scripts', implicitly routing scoring to calculate_band_score. It stops short of explicitly stating when to choose this over search_practice or analyze_writing.

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 openWorldHint=false, so the safety profile is fully covered. The description adds one useful semantic point — lesson quizzes are study checks, not IELTS scores — but says nothing about return shape, pagination, or ordering.

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 primary action. The trailing quiz clarification earns its place but is slightly tangential to the tool's mechanical behavior.

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

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

For a simple two-parameter read tool with annotations covering safety, this is close to sufficient. The absence of any listing output description (fields per lesson, ordering, whether lessonId is required vs. optional) leaves a small but real gap given there is no output schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does partially: 'writing or speaking' maps to the area enum and 'read one lesson in full by ID' maps to lessonId, but neither parameter is named or given format/validation detail.

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

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

States a specific verb and resource ('List the ... lessons') and adds a second mode ('read one lesson in full by ID'). The scope is clear and distinguishable from siblings like analyze_writing and get_sample_answer, though it never explicitly names an alternative.

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

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

The two modes (list all vs. fetch one by ID) imply when each is used, and the note about quizzes clarifies a study-check vs. IELTS-score distinction. However, no sibling is named and there is no explicit when-not guidance for a tool sitting next to search_practice and get_sample_answer.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond the annotations: the corpus is a closed set of original (non-official) practice questions and the return value is task IDs rather than full tasks. It stops short of describing result count defaults or empty-result 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?

Two compact sentences: the first front-loads what is searched and over what scope, the second covers the return value and the disclaimer. No filler, every clause carries 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 helpfully states the return format (task IDs) and the retrieval path. The main residual gap is parameter behavior for query/limit and questionType, but given a mostly-optional 0-required-parameter tool, the description is sufficient for correct invocation.

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

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

Schema description coverage is only 25% (only 'query' is documented), so the description must compensate. It partially does by enumerating the format categories that map to the 'format' enum, but adds nothing about 'questionType', the default/max on 'limit', or how 'query' matching works. Baseline 3 is appropriate given the partial compensation.

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

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

States a specific verb (Search) and a precise resource (original IELTS-style writing practice questions) with the covered scope spelled out (Academic Task 1/2, General Training Task 1/2). It also explicitly names the follow-up tool get_practice_task and disclaims official exam content, so an agent can distinguish it from siblings like search_vocabulary and get_sample_answer.

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

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

The phrase 'Returns task IDs for get_practice_task' establishes the intended workflow (search first, then fetch detail), which is strong contextual routing. 'Not official exam questions' sets an expectation boundary, but there is no explicit when-not-to-use guidance or statement of what to do when the search returns nothing.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful return-content context—entries include meaning, an example sentence, and a usage caution—but says nothing about limits, pagination, or result ordering, so it adds moderate value beyond the annotations.

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

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

The description is two short sentences and is front-loaded with the tool's purpose. However, the second sentence is IELTS writing advice rather than tool-invocation guidance, so it does not fully earn its place in a tool definition.

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 description coverage, the description needs to carry more weight. It states what the tool returns but omits any explanation of the query, topic, or limit parameters, leaving an agent under-informed about how 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% and the description does not mention any of the three parameters: limit, query, or topic. It adds no meaning beyond the schema for how to filter, constrain, or interpret the inputs.

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 'Search' and resource 'original IELTS vocabulary entries', and it lists the return content: meaning, example sentence, and usage caution. It does not explicitly differentiate from siblings such as search_practice or list_lessons, so it falls 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 gives no when-to-use or when-not-to-use guidance, and it never names an alternative tool. The second sentence is domain advice about using vocabulary correctly, not guidance for selecting this tool over search_practice or get_sample_answer.

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