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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. While it correctly states that the tool inserts a row into content_items, it does not mention what happens on success/failure, whether an ID is returned, how duplicates are handled, or any side effects beyond the insert. This leaves important behavioral expectations undisclosed.

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

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

The description is two sentences with no filler: one defines the operation and target, the other gives usage context. It is front-loaded and every sentence earns its place.

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

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

The schema is rich and fully documented, but the description is minimal relative to the tool's complexity (14 parameters, nested objects, no output schema). It correctly frames the tool as a dev-seeding utility, but does not explain expected return behavior, generated fields, or how the inserted item can be referenced afterward.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description itself adds no parameter-level meaning beyond the schema, but it does not need to because every parameter already has a clear description in the schema.

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

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

The description clearly states a specific action ('Inserts a new content item') and the exact resource ('content_items table'), making the tool's purpose unambiguous. It also differentiates from sibling tools like cl_add_reading_question, which operate on a different entity.

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

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

The description gives clear usage context: 'Use during dev sessions to seed reading passages, audio content, etc.' This tells an agent when it is appropriate to invoke the tool. However, it does not explicitly mention when not to use it or name alternative tools like cl_add_reading_question.

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

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

With no annotations present, the description carries the full burden. It transparently states that the tool performs an insert, so the mutating behavior is clear. However, it does not disclose return values, validation failures, whether duplicate inserts are allowed, or any required permissions or side effects beyond insertion.

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

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

Two concise sentences, front-loaded with the primary action and resource. Every sentence contributes useful information with no filler or repetition of schema content.

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

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

For a straightforward insert tool with a fully covered schema, the description communicates the essential purpose and required data. It lacks return/error behavior, but given the simple insert semantics and the absence of an output schema, the definition is sufficiently complete. The only notable gap is the lack of explicit guidance on the result of a successful insert.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description maps the core fields (passage, question, answer options, correct index) but adds little meaning beyond what the schema already provides. It omits mention of 'level' and 'sortOrder', but the schema covers those clearly.

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 ('Inserts a new reading comprehension question'), the exact resource ('the reading_questions table'), and the key data to provide. This clearly distinguishes it from sibling read-only tools like cl_get_reading_questions and from the more generic cl_add_content.

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

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

The description implies its use case: adding a reading comprehension question. However, it does not explicitly say when to prefer this over cl_add_content, nor does it state exclusions such as 'Do not use for non-reading content' or 'Use cl_get_reading_questions to retrieve existing questions.' The usage context is implied but not made 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?

The readOnlyHint annotation already signals safety, and the description adds meaningful behavior beyond that: it cross-references two named data sources and produces a coverage/gap analysis. There is no hint of side effects or hidden mutation, and the read-only framing is consistent with the annotation.

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

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

The entire description is one crisp sentence that front-loads the main verb and resource, then adds the purpose and role. Every phrase earns its place, and there is no filler or redundant restating of the tool name.

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

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

For a zero-parameter, read-only audit tool with no output schema, the description provides sufficient context: it names the inputs conceptually, describes the cross-referencing operation, and specifies what the report reveals. The sibling context further supports that this is a distinct reporting tool, and nothing important appears missing for an agent 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?

The tool has zero parameters and an empty input schema, so there is nothing for the description to elaborate. Per the baseline for zero-parameter tools, the description does not need to compensate for undocumented fields, and it introduces no ambiguity about 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 uses a specific verb ('cross-references') with clear resources ('grammar_feature_map' and 'content_items.language_features') and states the exact purpose: showing which grammar features have coverage and which are gaps. It also identifies the tool's role as 'the core instructional design audit tool,' which distinguishes it from siblings like cl_get_grammar_map or cl_get_content.

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

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

The phrase 'core instructional design audit tool' provides clear context for when this tool is appropriate: when auditing grammar coverage across content. It does not explicitly name alternatives or state when not to use it, so it stops just short of a 5, but the intended usage is easily 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?

The readOnlyHint annotation already signals safety, and the description adds meaningful behavioral detail: it reports escalation status, resolution, max tier, total interventions, and resolution counts. It does not contradict the annotation and provides a useful picture of the tool's output.

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

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

Two concise sentences: the first states the core purpose and the second enumerates the specific outputs. Every sentence earns its place and the most important information is front-loaded.

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

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

Although there is no output schema, the description lists the main returned values and the domain. It could go slightly deeper on how 'fossilization interventions' are defined or how results are grouped, but for a zero-parameter read-only tool this is largely sufficient.

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 and schema coverage is complete, so there are no parameter semantics to explain. The baseline of 4 applies because nothing is missing.

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

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

The description uses a specific verb ('Returns a summary') and identifies the exact resource ('fossilization interventions') plus the key metrics it covers. This clearly distinguishes it from sibling summary tools like session summaries or generated-content summaries.

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 relevant—whenever fossilization intervention status is needed—but it does not explicitly contrast it with alternatives or state when not to use it. With many sibling summary tools, some routing guidance would improve clarity.

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 readOnlyHint annotation already signals a safe read operation. The description adds useful non-obvious behavior: 'results are stratified across difficulty levels for even coverage' when no difficulty filter is set. This contextualizes a potential surprise in the returned data beyond what the 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?

The description is two concise sentences with no filler. It states the core function first and places the important stratification caveat in the second sentence, making it easy for an agent to parse quickly.

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

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

Given the readOnly annotation and fully documented parameters, the description is nearly complete. It explains the main behavior and a non-obvious default. It could be slightly richer by hinting at return format or providing an example, but the absence of an output schema is partially mitigated by the generic nature of 'content items.'

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

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

Schema description coverage is 100%, so the schema sufficiently documents all four parameters. The description briefly names the filter options (difficulty, topic, type) but does not add meaning beyond the schema fields. The baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Returns content items' with optional filters by difficulty level, topic, or type. It also highlights a distinguishing behavior—stratification when no difficulty filter is set—which separates it from the many sibling get_* tools.

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

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

The description implies when to use the tool: when you need content items, optionally with filters. However, it does not explicitly state when to prefer this over sibling tools like cl_get_reading_questions or cl_get_mystery_items, nor does it mention any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the description correctly adds behavioral context beyond that: data is aggregated, anonymized, and spans all users. This helps the agent understand the data scope without contradicting the read-only hint.

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 crisp sentences with no fluff. The primary function is front-loaded ('Returns aggregated error patterns...') and the use case follows naturally. Every word earns its place.

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

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

For a simple read-only tool with two optional parameters and no output schema, the description covers the core purpose and scope. It does not describe the return format or pagination behavior, but the limit parameter and the term 'patterns' give a reasonable hint. Overall, it is complete enough for its simplicity.

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

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

Schema description coverage is 100% (both limit and errorType have clear descriptions with defaults and enums), so the description does not need to add parameter-level details. The description adds no extra meaning about parameters, but the baseline 3 is appropriate.

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

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

The description clearly states it returns 'aggregated error patterns from error_logs across all users (anonymized)' — a specific verb, resource, and scope. It does not explicitly differentiate from sibling tools, but the mention of error logs and learning struggles gives enough distinction to be clear.

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 mentions it is 'useful for understanding where learners actually struggle,' which implies a use case, but it provides no explicit guidance on when not to use it or how it compares to alternatives like cl_get_grammar_map or cl_get_adaptation_summary.

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 readOnlyHint=true, and the description adds meaningful behavioral context beyond that: the data is aggregated, anonymized, and includes correctness rates. This helps the agent understand what kind of information to expect. It does not describe pagination or exact response structure, but the read-only annotation lowers the burden.

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

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

The description is two sentences with no redundancy. The core behavior is front-loaded in the first sentence, and the second sentence adds a succinct use case without unnecessary detail.

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

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

For a low-complexity read-only tool with two optional parameters and no output schema, the description provides sufficient context: what is returned, how it is scoped, and why an agent would use it. It could be slightly stronger by distinguishing itself from sibling reporting tools, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already thoroughly documents both parameters: limit and featureKey. The description adds no additional parameter-level meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Returns' and clearly identifies the resource: aggregated feature exposure data with per-feature view counts and correctness rates. It effectively describes the tool's function, though it does not explicitly contrast it with similar reporting siblings like cl_coverage_report or cl_get_error_patterns.

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

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

The description states a clear use case: 'Useful for finding undertaught or poorly-performing features.' This gives an agent explicit context for when to invoke the tool. It does not provide exclusions or name alternative tools, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, and the description aligns with that. The description adds the 'Anonymized' detail and clarifies the aggregated nature of the data, which is useful context beyond the annotation. No contradiction.

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

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

Two concise sentences with no filler. The first sentence front-loads the key outputs, the second gives a use case. Efficient and well-structured.

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 summary tool with optional filters, the description covers the purpose, key outputs, and use case. It does not specify the output format, but since no output schema is provided, the description could benefit from that, though the core information needed for selection is present.

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?

Both parameters (limit and contentType) are described in the schema with 100% coverage. The description adds no additional parameter-specific semantics beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states a specific verb 'Returns' and a specific resource 'aggregated stats on AI-generated content', listing concrete metrics (types, error targets, listening rates, TTS costs). It does not explicitly name a sibling, but the purpose is distinct enough from siblings like cl_get_tts_usage which focuses on TTS usage details.

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

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

The description provides a use case ('Useful for auditing the AI tutor's output quality and cost') but does not explicitly state when not to use it or mention alternative tools. The usage context is implied rather than explicitly contrasted with siblings.

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

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

Annotations provide readOnlyHint=true, which is helpful, and the description adds meaningful behavioral context by stating that it returns all entries unless filtered and enumerates the output fields. This goes beyond the annotation without contradicting it.

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

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

A single, well-structured sentence that front-loads the core behavior and then specifies the optional filter and return fields. No filler or redundant restatement of the tool name.

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 lookup with one optional parameter and no output schema, the description is complete: it states the source, the filter, and the returned content fields. Nothing essential is missing for an agent 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?

The input schema already documents the single optional parameter and its enum values, so schema description coverage is 100%. The description merely echoes the CEFR-level filter without adding new semantic detail.

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

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

The description uses a specific verb ('Returns') and a specific resource ('grammar_feature_map'), then lists the fields returned. This clearly differentiates it from siblings like cl_get_schema or cl_get_content, which target different resources.

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

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

The description implies when to use it: whenever you need grammar feature map entries, optionally filtered by CEFR level. However, it does not explicitly name alternative tools or state when not to use it, leaving some 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 readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: results are AI-generated, periodic, anonymized, and include stats. It does not describe the exact return shape, but the description still adds meaningful value beyond the annotation.

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

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

Two concise sentences with no filler. The main action and resource are front-loaded, and the second sentence adds a legitimate use case. Every part earns its place.

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

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

For a simple read-only tool with one optional parameter and an annotation covering safety, the description is nearly complete. It explains what the tool returns and why an agent would use it. It could be slightly stronger with an explicit mention of sibling alternatives, but no critical information is missing.

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

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

The input schema has full coverage for the single 'limit' parameter, including default, min, and max. The description does not add much parameter-specific detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('Returns') and resource ('AI-generated learning narrative summaries') with meaningful detail about what these are: periodic reflections on learner progress with stats. It implicitly distinguishes this tool from siblings like session/proficiency summaries, though it does not name an alternative 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?

The description gives a concrete use case: 'useful for auditing narrative quality and checking if the reflection system captures meaningful patterns.' This provides clear context for when to call the tool, though it does not explicitly discuss when not to use it or name sibling alternatives.

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 readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by explaining what the returned items represent and which attributes are included. It also clarifies the explored-status distinction, which helps an agent understand the tool's semantics beyond a bare 'get items' label.

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 short, front-loaded with the main action, and structured with a clear field list in the second sentence. The final sentence adds a general use case but is somewhat vague; still, the overall text is efficient and easy to parse.

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

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

For a simple read-only getter with two optional parameters and no output schema, the description covers the key return fields and the exploring/explored distinction. It is mostly complete, though a bit more detail about the exact response shape or ordering would help since no output schema is provided.

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

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

Schema description coverage is 100%, so the parameter descriptions for 'limit' and 'explored' already provide the necessary semantic meaning. The description references the explored concept but does not add material detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Returns') and a specific resource ('mystery vocabulary items'), then enumerates the included fields (word, context, definition, examples, grammar, explored status). This is clear, but it does not explicitly differentiate the tool from its many get_* siblings, such as cl_get_content or cl_get_error_patterns.

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 'Useful for understanding organic vocabulary discovery' implies a use case but does not specify when to choose this tool over alternatives or when not to use it. There is no explicit guidance on selecting it among the sibling tools, though the purpose is understandable.

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

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

The description discloses that the operation is recursive and caps depth at 10, which is meaningful behavioral information beyond the readOnlyHint annotation. It does not contradict the annotation and gives a useful constraint for agents deciding whether the result will be complete.

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 core action and resource, then adds the purpose and the depth cap. Every phrase earns its place with no redundant or vague 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 simple read-only tool with one parameter, the description is largely complete: it explains the input, the output concept, the recursion, and the cap. It does not describe the exact return format or ordering, but no output schema exists, and the missing details are unlikely to prevent correct invocation.

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

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

Schema description coverage is 100%, so the schema already explains featureKey as 'The feature_key to trace prerequisites for.' The description adds the notion of a recursive chain but does not materially enhance parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description names a specific verb ('returns'), a specific resource ('full recursive prerequisite chain'), and a clear purpose ('audit whether the sequencing is pedagogically sound'). This distinguishes it from sibling tools like cl_get_grammar_map or cl_get_content, which serve different purposes.

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

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

The description clearly implies when to use it: when you need to trace prerequisites for a specific grammar feature to evaluate pedagogical sequencing. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it appropriately among the many sibling tools.

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

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

The readOnlyHint annotation covers the safety profile, and the description adds meaningful behavioral context beyond it: the data is anonymized, aggregated across all users, and broken out by skill and period. This helps an agent understand the scope and nature of the returned data without contradicting the annotation.

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

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

The description is two concise sentences with the core action and resource front-loaded. It includes the essential scoping detail, the dimensions, the aggregation behavior, and a use case without redundancy.

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

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

Given the low complexity (one optional parameter, readOnly annotation, no required inputs, no nested schema), the description is complete enough for an agent to decide when to call the tool and what to expect. It explains the resource, the dimensions, the aggregation, and the intended value, with the parameter already documented in the 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 100%, with the single 'limit' parameter fully documented including default, minimum, and maximum. The description does not add further meaning to the parameter, but it does not need to because the schema already carries that burden.

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

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

The description opens with the specific verb 'Returns' and identifies the exact resource: proficiency score history over time. It further specifies the dimensions (overall, listening, reading, speaking, writing) and the aggregation scope (anonymized across all users), making it clearly distinguishable from the sibling tools focused on error patterns, sessions, or narratives.

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 final sentence gives a clear use case: 'tracking whether content improvements translate to learner gains.' This provides explicit context for when the tool is useful, though it does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already mark readOnlyHint=true, so safety is covered. The description adds what the response contains (passage text, question, answer options, correct index) and that filtering by level is optional, which is useful behavioral and output context beyond the schema.

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

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

Two short sentences, front-loaded with the main action and output details, followed by a practical use case. No filler or repetition of schema content.

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

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

For a simple read-only list tool with two optional, self-explanatory parameters, the description is complete: it states what is returned, the optional filter, and the intended purpose. The output fields are enumerated without requiring an output schema, and annotations cover the safety profile.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond repeating the optional CEFR filter; the limit parameter is only documented in the schema, but the schema already handles that adequately.

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

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

The description clearly states the tool returns reading comprehension questions and can filter them by CEFR level, and it names the key output fields. It does not explicitly distinguish itself from siblings like cl_get_suggested_questions, but the 'auditing' framing adds specificity beyond the title.

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

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

The description provides a clear use case: auditing question quality and level coverage. It does not mention alternative tools or when not to use it, but the auditing context gives enough guidance for typical selection.

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

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

The readOnlyHint annotation already signals safe read behavior, and the description does not contradict it. The description adds orientation context but does not disclose additional behavioral details such as response size or whether all tables are included unconditionally.

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 carry both the operational result and the recommended use case. The description is front-loaded with the core purpose and contains no filler.

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

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

For a parameterless, read-only schema-listing tool, the description is fully sufficient. It tells the agent what the tool returns and when to use it; no further information is needed 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?

The tool has zero parameters, so the no-parameter baseline of 4 applies. There is nothing for the description to clarify about inputs, and the schema already reflects the absence of parameters.

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

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

The description clearly states a specific verb ('Returns') and a specific resource ('summary of all tables and their columns in the ChaosLimba database'). It differentiates itself from sibling tools that target grammar, content, or coverage by centering on the database schema 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?

The description gives explicit when-to-use guidance: 'Use this to orient yourself when first connecting.' It does not name alternative tools or exclusions, but for a zero-parameter orientation tool the context is clear enough.

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 readOnlyHint annotation already signals no side effects. The description adds valuable behavioral context beyond that by disclosing that all data is anonymized and that no user IDs are returned, which is important for privacy-aware tool selection. It does not contradict the annotation.

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

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

Two compact sentences with no filler. The first sentence front-loads the core data delivered, the second adds the anonymization caveat and practical use case. Every sentence earns its place.

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

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

For a low-complexity read-only tool with 2 optional parameters, a complete schema, and no output schema, the description provides enough information to call it correctly. It states what data is returned, confirms privacy/anonymization, and gives a realistic usage scenario.

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

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

Schema coverage is 100%, with both 'limit' and 'sessionType' already described clearly in the input schema. The description adds minimal parameter-specific meaning, though 'session counts by type' loosely aligns with the sessionType filter. The schema carries the full burden, so baseline 3 applies.

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

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

The description states a specific verb ('Returns') and resource ('aggregated session data'), and itemizes what that includes: session counts by type, average duration, and content engagement. This clearly distinguishes it from the many get_* siblings, which target grammar maps, content, error patterns, etc.

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

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

The description gives clear usage context: it is useful for understanding how learners use the app. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous enough for an agent to select this tool for high-level session analytics.

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 readOnlyHint annotation already marks the operation as safe, and the description's 'Returns' aligns with that, so there is no contradiction. Beyond the annotation, the description adds domain context about what stress minimal pairs are, but it does not disclose operational behaviors such as ordering, randomness, or how the limit parameter affects the result set. The added context is useful but not rich 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?

The description is a single front-loaded sentence that immediately states the action and resource, followed by a useful parenthetical example and a short context clause. There is no filler, and every element contributes to understanding what the tool returns and why it matters.

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, fully documented parameter and no output schema. The description tells the agent what data is returned and its domain, while the schema covers the limit parameter completely. Nothing essential for a correct call is missing.

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

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

The schema fully documents the lone 'limit' parameter, including a description, default, and min/max bounds, so the description does not need to explain it. The tool description itself mentions no parameter details and adds nothing beyond what the schema already provides, earning the baseline score of 3.

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

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

The description uses a specific verb 'Returns' and a precise resource 'stress minimal pairs', clarifying exactly what the tool provides. The concrete example 'CÁsă vs caSĂ' and the phrase 'Core pronunciation training data' clearly distinguish it from sibling tools like cl_get_error_patterns or cl_get_grammar_map, making the purpose unambiguous.

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

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

The description implies that this tool is for retrieving pronunciation training data about stress placement, but it gives no explicit when-to-use guidance. It does not name alternatives or exclusions, such as when to prefer cl_get_error_patterns. The context 'Core pronunciation training data' is helpful but leaves selection criteria 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?

The readOnlyHint=true annotation already establishes this as a safe read operation. The description adds useful context about what is returned and that filtering is possible, but it does not disclose return format, ordering, or any behavior beyond what the schema parameters imply. This is moderate but not rich behavioral 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?

The description is two sentences with zero fluff. The first sentence front-loads the action and resource, and the second sentence adds a practical use case. Every clause earns its place.

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

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

For a simple read-only getter with three optional parameters and no output schema, the description covers what is returned, the filter options, and the intended use. The schema handles parameter constraints and the annotation covers safety, so an agent has enough to invoke the tool correctly. Minor gaps like return structure are acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, so all three parameters already have clear descriptions, defaults, and constraints. The description only restates the filtering capability without adding extra semantics such as accepted category formats or how limit interacts with filters, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Returns'), a clear resource ('AI tutor conversation starter questions'), and the optional filters (CEFR level or category). This resource is distinct from siblings like cl_get_reading_questions or cl_get_tutor_openings, so an agent can tell them apart without inspecting schemas.

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

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

The description provides a use case ('auditing prompt quality and topic coverage') that hints at when to use it. However, it does not explicitly name alternatives or explain when not to use this tool, leaving the agent to infer the distinction 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?

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds useful behavioral context by specifying the statistic is characters consumed per day, but it does not disclose the return format or any potential quirks. For a simple read-only stats tool, this is adequate but not rich.

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

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

Two sentences with no filler: the first states the tool's function and metric, the second states its purpose. The information is front-loaded and every word contributes value.

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

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

Given the tool's simplicity, one optional parameter, full schema coverage, and readOnly annotation, the description is nearly complete. It could clarify the output shape (e.g., a time series of daily character counts), but this is a minor gap for a straightforward usage-stats endpoint.

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

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

Schema description coverage is 100%, with the single 'days' parameter fully documented including default, minimum, and maximum. The description does not need to repeat parameter details; the baseline of 3 applies since the schema carries the semantic weight.

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

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

The description states a specific verb and resource: 'Returns TTS (text-to-speech) usage stats — characters consumed per day.' This clearly identifies the tool's function and metric, and it is distinct from all sibling tools, none of which relate to TTS usage or cost monitoring.

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

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

The description provides explicit use context: 'Useful for monitoring costs and usage trends.' There are no analogous sibling tools for TTS usage, so an explicit alternative comparison is unnecessary; the intended use case is clear enough for an agent to select this tool.

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

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

The readOnlyHint annotation already signals safety, and the description adds that results are keyed by self-assessment level. However, it does not disclose other behavioral details such as whether all entries are returned by default, ordering, or error behavior. This is acceptable for a simple read-only tool but not exceptional.

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 communicate the resource, the keying mechanism, and the purpose without wasted words. The essential behavior is front-loaded in the first sentence.

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 tool with one optional parameter and no output schema, the description is largely sufficient: it names the returned resource and its organization. Slightly more detail about default behavior without a filter would make it fully complete, but the current description is adequate 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 coverage is 100%, so the parameter is already documented. The description adds meaning by connecting 'self-assessment key' to 'self-assessment level' and 'proficiency levels,' clarifying what the filter represents beyond the schema's generic 'Filter by self-assessment key.'

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 identifies the tool as returning tutor opening messages and further specifies that they are keyed by self-assessment level. This distinguishes it from sibling getter tools such as cl_get_content or cl_get_adaptation_summary.

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 purpose statement implies usage context—call this to see tutor greetings at different proficiency levels—but there is no explicit when-to-use guidance or comparison with alternative sibling tools. The optional filter is mentioned in the schema, not in the description.

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