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

Annotations indicate a non-read-only, non-idempotent, non-destructive operation, and the description confirms the creation effect with 'Add a new study area.' However, it adds little beyond this: no details about duplicate-name behavior, permissions, or return value are provided.

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 short sentence with no filler or redundancy. The core action is front-loaded and appropriately sized for a simple one-parameter tool.

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

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

For a one-parameter create operation, the description is minimally sufficient, but it leaves gaps around the study hierarchy and behavior on success. Since siblings include create_topic and create_subtopic, specifying that a study is the parent-level entity would improve completeness.

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 required 'name' parameter with the description 'Human-readable study name.' The tool description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Add') and resource ('study area'), matching the tool name. It clearly refers to creating a study-level entity, but it does not explicitly distinguish itself from the sibling create_topic and create_subtopic 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?

No guidance is provided about when to use create_study versus create_topic or create_subtopic. The description simply states the action and gives no exclusions, prerequisites, or routing 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 already establish that this is a write operation (readOnlyHint=false) and not idempotent or destructive. The description adds only the hierarchical relationship ('under a topic') and does not discuss failure behavior, uniqueness, whether the parent must exist, or what happens on success. It does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the core operation and hierarchy relationship in minimal words while remaining unambiguous.

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 3-parameter creation tool with full schema coverage and annotations, the description is minimally viable. However, it omits helpful context such as the need for the parent topic to exist, any return behavior, and how duplicates are handled. This is not critical for invocation but leaves several edge-case questions unanswered.

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 parameters are fully documented in the schema. The description adds no parameter-specific detail, which is acceptable because the schema already explains topic_id, name, and description sufficiently.

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 ('Add') and a specific resource ('a subtopic under a topic'), immediately establishing that this creates a child of a parent topic. This clearly differentiates it from sibling create_topic while remaining easy to understand.

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 'under a topic' implies this should be used only when there is an existing parent topic, but the description gives no explicit when-to-use guidance or mention of alternatives like create_topic for top-level topics. The usage context is inferable, not stated.

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

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

Annotations already convey that this is a mutating, non-idempotent operation, so the description does not need to restate that. It adds the useful constraint that topics are parented to a study. It doesn't mention consequences like duplicate-name behavior or whether the study must already exist, but this is a minor gap for a simple create.

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?

At seven words, the description is tightly scoped and front-loaded with the verb and object. There is no filler or 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 two-parameter creation tool, the description plus the fully documented schema is nearly sufficient. It supplies the parent relationship, while the schema supplies field semantics. It would be slightly stronger with an explicit note on uniqueness or an alternative-tool pointer, but nothing essential is missing to make the 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?

The input schema covers 100% of parameters, including a helpful clarification on study_id ('never a user id'), so the description does not need to elaborate. It adds no param-level detail beyond the schema, earning the baseline 3.

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

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

The description states a clear action ('Add') on a specific resource ('a topic') with an explicit parent scope ('under a study'). It is not a tautology and maps cleanly onto the required study_id parameter. It doesn't explicitly contrast with create_subtopic, but the hierarchical wording is enough to set it apart.

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

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

The description conveys only that this tool is for adding topics under a study; it gives no explicit when-to-use or when-not-to-use guidance relative to siblings like create_subtopic or create_study. The correct usage is implied by the hierarchy in the wording, but no alternatives or exclusions are named.

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; the description adds meaningful context by specifying hard-delete semantics (permanent removal) and requiring explicit confirmation. This goes beyond the structured hints without contradicting them.

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

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

One efficient sentence conveys scope, permanence, and the confirmation requirement without wasted wording. Every phrase 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?

For a single-parameter destructive action with strong annotations and no output schema, the description is sufficiently complete. It explains what happens, to whom, with what permanence, and under what condition, leaving no critical gap for invoking the tool correctly.

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

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

Schema description coverage is 100%, and the single confirmation parameter already documents the exact required string. The description only echoes the need for explicit confirmation, adding no new parameter-level detail beyond what the schema provides.

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

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

States a specific verb ('hard-delete'), a clear resource ('all study data for the authenticated user'), and a distinct scope that separates it from per-resource siblings like delete_study, delete_topic, and delete_subtopic. The phrase 'all study data' removes ambiguity about what gets removed.

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

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

The description makes clear this is the tool for deleting the entire authenticated user's study data, and the 'after explicit confirmation' qualifier sets the expected precondition. It does not explicitly name alternatives or say when not to use it, but the scope and sibling list make the intended usage inferable.

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

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

Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds meaningful behavioral context by specifying that the deletion is a soft-delete and that history is preserved, which clarifies the tool's effect beyond the raw annotation flags. This is useful context for an agent deciding whether calling this tool is safe and what consequences to expect.

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 with no wasted words. However, it sacrifices important scope information (topics/subtopics) for brevity, so it is concise but not optimally complete.

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

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

For a simple one-parameter tool, the description is underspecified. It omits that the id may reference a topic or subtopic, does not differentiate from sibling delete_topic and delete_subtopic, and does not clarify whether soft-deletion means the item disappears from listings or how history is surfaced. The schema covers the parameter, but the tool-level description leaves important selection and behavioral questions unanswered.

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%, and the parameter description is already informative: 'Id of the study, topic, or subtopic to soft-delete for the authenticated user.' The tool description adds no additional parameter-level meaning, so the baseline score of 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 names a clear action and resource: 'Soft-delete a study while preserving history.' However, it understates the actual scope: the input schema says the id can be a study, topic, or subtopic, and sibling tools delete_topic and delete_subtopic exist, so the description does not distinguish which tool applies to which resource type. This creates ambiguity about whether delete_study is only for studies or also for topics/subtopics.

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 guidance on when to use this tool versus delete_topic, delete_subtopic, or delete_my_data. It does not explain whether topics/subtopics should be deleted through this tool or through their dedicated siblings. No exclusions or alternative routing are provided.

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 explicitly discloses that deletion is soft and history is preserved, adding meaningful context beyond the annotations' destructiveHint=false. It is consistent with idempotentHint=true, though it does not explain repeated-call behavior or downstream effects on related data.

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 with no filler. Every word contributes: the action, the resource, and the key behavioral qualifier.

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

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

For a simple one-parameter soft-delete operation, the description is mostly adequate, especially with annotations covering safety and idempotency. But it leaves unresolved the schema's broader id description and the practical effects of soft deletion, such as visibility in list_subtopics or whether history remains queryable via get_subtopic_history.

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 and the description does not need to repeat parameter details. However, the schema's id description ambiguously mentions study, topic, or subtopic, and the description does not resolve this inconsistency or clarify whether only subtopic ids are valid.

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

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

The description uses a specific verb and resource, 'Soft-delete a subtopic,' and adds a meaningful qualifier, 'while preserving history,' which distinguishes it from hard-delete operations. However, the schema's id description says 'study, topic, or subtopic,' which muddies exactly what resource the tool deletes.

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 about when to use this tool versus delete_topic, delete_study, or delete_my_data. The description does not state exclusions, prerequisites, or consequences such as whether soft-deleted subtopics disappear from listings or can be restored, so the agent must infer usage 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 convey non-destructive and idempotent behavior, and the description adds valuable context by explicitly saying 'soft-delete' and 'preserving history.' This explains why destructiveHint is false and clarifies that history is retained, going beyond the structured annotations.

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

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

The description is a single front-loaded sentence with no filler. Every word adds value, and the key behavioral qualifier 'while preserving history' is included without bloating the text.

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 tool with one required parameter, full schema coverage, and annotations, the description is nearly sufficient. The only notable ambiguity is that the id accepts study, topic, or subtopic while the description says 'topic,' but the schema resolves this at call time.

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

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

Schema description coverage is 100%, so the input schema fully documents the id parameter. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the operation—'Soft-delete a topic while preserving history'—with a specific verb and resource. It does not explicitly differentiate from sibling delete_study/delete_subtopic, and the id schema's 'study, topic, or subtopic' scope introduces minor ambiguity, 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 guidance about when to use this tool instead of delete_study or delete_subtopic, nor when not to use it. The resource name implies scope, but the broader id description makes the lack of explicit routing a meaningful gap.

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 scope context ('all study data', 'authenticated user') but does not disclose behavioral details like output format, download behavior, or whether the export is synchronous or asynchronous.

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, tightly worded sentence with no filler. It front-loads the key information: the operation, the resource scope, and the user scope.

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 export tool, the description is mostly complete. It could be improved by noting the output format or return behavior, but the annotations and low complexity reduce the need for extensive elaboration.

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 description coverage is 100%, so there is no parameter meaning left to clarify. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on what the tool does rather than 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 states a specific verb ('Export'), a clear resource ('all study data'), and a scoping qualifier ('for the authenticated user'). This distinguishes it from sibling tools like list_studies, which only list a subset, and delete_my_data, which is destructive.

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 guidance is provided about when to use this tool versus alternatives such as list_studies or get_subtopic_history. The description does not state whether this is for backups, data portability, or bulk retrieval, 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 establish readOnly, idempotent, and non-destructive behavior. The description adds the meaningful trait that results are sorted by overdue-ness, but it does not disclose scope behavior when study_id is omitted or what fields the queue items contain. With annotations covering safety, 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?

A single, front-loaded sentence with no filler. Every word contributes to the core purpose and ordering behavior, making it easy for an agent to process 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?

For a read-only tool with two optional, fully documented parameters and safety annotations, the description covers the essential purpose and ordering. The main omission is behavior when study_id is null (all studies vs. a default scope) and the absence of an output schema, but the low complexity and strong schema/annotation coverage make this 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 100%, so the baseline is 3; the schema already explains limit and study_id, including the warning that study_id is not a user id. The description adds no parameter-level detail beyond the fact that the returned queue is ordered by overdue-ness.

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 clear action and resource: returning the spaced-repetition queue ordered by overdue-ness. It is understandable, though it relies on the tool name and the phrase 'spaced-repetition queue' to convey that it returns due subtopics, and it does not explicitly contrast with siblings like list_subtopics.

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

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

The description implies the tool is for retrieving the review queue, so an agent can infer when to call it, but it provides no explicit when-to-use or when-not-to-use guidance and names no alternatives. The sibling tools are visible in context, yet the description does not route the agent to list_subtopics or get_subtopic_history when a different view is needed.

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 established. The description adds context about what data is returned (attempts, trend, state) but discloses no additional behavioral traits such as error conditions, empty result handling, or rate limits. It is consistent with annotations and adds modest value beyond them.

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

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

The description is a single, concise sentence that front-loads the action ('Return') and the resource ('attempts, trend, and state for one subtopic'). Every word earns its place, with no filler or repetition of schema details.

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

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

This is a simple read-only tool with one parameter and no output schema. The description names the three kinds of returned information, which is sufficient for an agent to understand the tool's purpose and basic expected output. It could be more detailed about the exact structure or semantics of 'attempts, trend, and state,' but for the low complexity, it is adequately 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?

The input schema provides 100% coverage with a clear description for subtopic_id: 'Subtopic id returned by list_subtopics or create_subtopic; never a user id.' The tool description adds no new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Return attempts, trend, and state for one subtopic.' It is unambiguous about what the tool does and clearly distinguishes itself from sibling list tools like list_subtopics or get_due_subtopics by targeting a single subtopic's history.

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

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

The phrase 'for one subtopic' gives clear context for when to use this tool: when attempting to retrieve historical data about a specific subtopic. It doesn't explicitly name alternatives or exclusion conditions, but the purpose is specific enough that an agent can infer appropriate usage relative to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safely profile. The description adds the 'active' scoping, which is useful, but it does not disclose return shape, ordering, or pagination details.

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 sentence with no wasted words. It front-loads the action and resource, and every word contributes meaning.

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 no-argument read-only list operation, the description is minimally sufficient. However, with no output schema it leaves the return-value structure unstated, and it does niot clarify how 'study areas' relate to the topic/subtopic sibling 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 tool has zero parameters and schema description coverage is 100%, so there is no parameter semantics for the description to add. The baseline of 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?

The description states a specific verb and resource: 'Return all active study areas.' It is not a tautology and is clearly about listing studies rather than topics or subtopics, though it does not explicitly name sibling tools to differentiate 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?

No when-to-use or when-not-to-use guidance is provided, and no alternative sibling tools are referenced. The intended usage is only implied by the purpose statement, so an agent must infer when this tool is preferred over list_topics or list_subtopics.

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 establish a safe, idempotent, read-only operation. The description adds useful context by restricting to 'active' subtopics and noting 'current mastery state', but it does not disclose additional behavior such as output shape, ordering, or pagination.

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 with no filler. Every term ('Return', 'active', 'within a topic', 'current mastery state') adds signal and helps scope the operation.

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, single-parameter, read-only list tool, the description plus annotations and schema are mostly sufficient. The only real gap is the lack of an explicit output structure or mention of whether inactive subtopics are excluded beyond the word 'active', but the tool's simplicity keeps this from being a major omission.

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 fully describes the only parameter, topic_id, including where it comes from and a caution that it is never a user id. Since schema description coverage is 100%, the description does not need to add parameter-level meaning, and the baseline of 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 ('Return'), a specific resource ('active subtopics within a topic'), and the distinguishing output ('current mastery state'). This clearly separates it from siblings like list_topics, get_due_subtopics, and get_subtopic_history.

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

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

The description clearly frames when to call it: when listing active subtopics of a topic and needing current mastery state. It does not explicitly name alternatives like get_due_subtopics or get_subtopic_history, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'active' scoping detail, which is useful, but it does not mention ordering, pagination, or the exact shape of returned topics.

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 contains the core action, the resource, and the active-topic filter. There is no redundancy or 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, single-parameter tool, the description plus schema and annotations are mostly adequate. It could be more complete by explicitly noting what fields are returned for each topic, but nothing needed to safely invoke the tool is missing.

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

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

The schema covers 100% of the parameter and already describes study_id as returned by list_studies or create_study, and warns it is never a user id. The description adds little beyond the word 'study,' but the schema is sufficient, 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 uses a specific verb ('Return') plus a clear resource and scope: 'active topics within a study.' This immediately distinguishes it from siblings like list_studies (studies, not topics) and list_subtopics (subtopics, not 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?

The phrase 'within a study' implies the tool is for study-scoped topic listing, and the 'active' filter further narrows intent. However, there is no explicit statement about when to prefer this tool over list_subtopics or get_due_subtopics, nor any when-not-to-use guidance.

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

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

Annotations are all false, so the description carries the burden of behavioral disclosure. It does disclose that the tool records data and mutates SM-2 state, which is useful. However, it does not say whether multiple attempts accumulate, whether prior attempts are overwritten, or what scheduling fields are affected.

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 with no filler. It states the primary action and the key side effect efficiently, 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?

For a mutation tool with four fully documented parameters, the description plus schema is largely sufficient for an agent to invoke it correctly. It does not detail the return value or exact scheduling changes, but those are secondary given the clear action and complete 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%, and the schema already documents each parameter, including the score rubric and subtopic_id clarification. The description adds no parameter-specific meaning, 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 uses a specific verb ('Record') and resource ('quiz attempt') and also names the side effect ('update SM-2 scheduling state'). This clearly differentiates it from sibling list/get/update tools and leaves no doubt about the action.

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

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

The description implies clear usage context: call it when a quiz attempt has been graded and SM-2 scheduling state should be updated. It does not explicitly name alternatives or exclusions, but no sibling tool competes for this action, so the context is sufficient.

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

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

Annotations already indicate this is not read-only and not explicitly destructive; the description's 'Edit' is consistent but adds no behavioral context beyond that. It does not disclose merge semantics for null fields, return value, permissions, or side effects, so it provides little transparency beyond the structured annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It is concise, though slightly repetitive of the tool name and parameter names, so it does not reach the exceptional level of fully optimized descriptions.

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 update tool with a fully documented schema and annotations, the description is minimally adequate. However, it omits useful context like partial-update behavior, whether null clears or preserves fields, and what the tool returns, so an agent would benefit from more guidance.

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 parameters are already well documented. The description only restates the field names 'name' and 'description' without adding new semantic meaning such as what omission or null means for each field.

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 ('Edit') and resource ('subtopic') and names the editable fields ('name or description'). It is clear enough to be distinguished from create_subtopic, delete_subtopic, and list_subtopics, though it does not explicitly call out alternatives.

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

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

The description gives no guidance on when to use this tool versus siblings such as create_subtopic, delete_subtopic, or list_subtopics. There are no prerequisites, exclusions, or alternative routing, so an agent must infer usage solely from the verb 'Edit'.

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