HiveLearn

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses idempotency, which is valuable, but omits other important behaviors: what happens if the tag or member does not exist, whether it is a pure mutation, what the return value structure is, and any error conditions. For a write operation with zero annotation coverage, this is under-disclosed.

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 with no fluff. The primary purpose is front-loaded, and the idempotency note is a single efficient clause. 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 two-parameter assignment operation, the description is adequate but incomplete. It lacks information about return value shape (beyond 'existing assignment'), error behavior, and whether the tag or member must already exist. Given no output schema and no annotations, more context would help an agent call it correctly.

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

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

Schema coverage is 100% with descriptive parameter comments ('Tag uuid from list_member_tags' and 'Member's user (profile) uuid, not the membership row id'). The description adds nothing beyond the schema, but with full coverage the baseline is 3, and the description does not need to compensate.

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 verb ('Assign') and resource ('tag to a member'), and the idempotency note adds useful semantics. However, it does not explicitly distinguish itself from the sibling hivelearn_create_member_tag, which could confuse an agent about when to create a tag versus assign an existing one.

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 idempotency statement gives some usage guidance (safe to retry), but there is no explicit when-to-use vs alternatives, no mention of prerequisites (tag must exist, member must exist), or when not to use. The distinction from create_member_tag is left to the name rather than described.

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

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

No annotations are provided, so the description carries the transparency burden. It does disclose useful behaviors: sort_order defines ordering, unlock_after_course_id gates completion, and is_required defaults to true. However, it does not mention side effects such as what happens if the course already exists in the track, validation errors, or the return value. This is adequate but not exhaustive.

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 three compact sentences, each carrying useful information. It front-loads the primary purpose and then explains the two most nuanced parameters and a default. There is no redundancy or fluff.

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 add operation with no output schema, the description covers the essential aspects: what the tool does, how ordering works, how prerequisites work, and the default for is_required. It does not describe the response format or duplicate-handling behavior, but given the tool's simplicity and the absence of an output schema, this is a minor gap.

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

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

Schema description coverage is 60%, and the description compensates by clarifying the semantics of key parameters: 'sort_order sets the order within the track', 'prerequisite course that must be completed first', and 'is_required defaults to true'. Track_id and course_id are self-explanatory names, so no additional detail is needed.

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

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

The description opens with a specific verb and resource: 'Add a course to a track at a given position.' It clearly distinguishes this from sibling tools like create_course (which creates a new course) and create_track (which creates a track). The position aspect is a unique differentiator.

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

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

The description provides clear context that this tool is for adding an existing course to an existing track, with positioning and prerequisites. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough for an agent to select it over related 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?

No annotations are provided, so the description carries the full burden. It discloses that this is a mutation that bypasses the normal automated process, but it does not mention permissions, idempotency, what happens if a certificate already exists, or the return value. These are significant gaps for a manual issuance tool.

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

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

The description is two sentences, front-loaded with the main action and purpose, and contains no unnecessary filler. Every sentence adds 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 six parameters, no output schema, and no annotations, the description should cover prerequisites (e.g., enrollment/completion), duplicate handling, and return behavior. It covers only the core purpose and when to use it, leaving major operational details unaddressed.

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

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

Schema description coverage is only 33%, and the description does not compensate. It only implies user_id and course_id; final_score, instructor_name, and completion_date are not explained, and expires_at/completion_date semantics are left entirely to the schema. The description adds no meaningful parameter-level 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 ('Issue') and clearly identifies the resource ('certificate of completion') and target ('a user for a course'). It also distinguishes itself from sibling certificate tools (get, update, verify, list) by framing this as an issuance action, and differentiates from the normal auto-issuance flow.

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

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

The description explicitly states when to use this tool: 'Normally the platform auto-issues on course completion — use this tool for bulk backfill or manual awards.' This provides direct when-to-use guidance and contrasts it with the automatic alternative.

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

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: the created course will be empty of modules/lessons. While it doesn't mention return values or permissions, for a create operation this scope clarification is valuable and meets the transparency bar.

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

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

The description is two sentences, front-loaded with the primary action. The second sentence efficiently provides an alternative. Every word earns its place, with no redundant information.

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

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

For a 10-parameter tool with no annotations and no output schema, the description gives the core purpose and alternative guidance, but leaves parameter details to the schema, which is mostly undocumented. It is minimally viable but lacks richness; additional details on required fields or default behavior 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?

Schema description coverage is only 10% (only 'visibility' has a description), yet the description adds no parameter-specific meaning. It does not explain fields like 'description_json' or 'difficulty', leaving the agent to infer from names. Since coverage is low, the description needed to compensate but did not.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create an empty course'. It explicitly notes 'no modules/lessons', distinguishing it from creation tools that scaffold structure. It also differentiates from the sibling tool hivelearn_create_course_outline, 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?

Provides explicit guidance: 'Prefer hivelearn_create_course_outline when you already know the structure — it scaffolds course + modules + lesson placeholders in one call.' This tells the agent exactly when to use this tool versus an alternative, which is high-quality usage guidance.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It transparently states that only placeholders are created ('no content yet') and that it returns lesson ids for a follow-up loop, revealing the composite create behavior. It does not mention potential side effects, permissions, or idempotency, but for a create-style tool, the essential behavior is clearly conveyed.

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 three sentences, all of which are information-dense and earn their place. It front-loads the primary action, then explains the follow-up, then gives a clear usage preference. There is no repetition or fluff.

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

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

The tool is fairly complex (11 params, nested objects, no output schema), and the description provides a solid high-level overview but leaves gaps. It explains the course outline concept and the follow-up update step, but it does not describe the full return structure (e.g., course id, module ids) or any prerequisites. Since there is no output schema, the description should more fully cover return values and overall workflow.

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

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

Schema description coverage is only 9% (only 'modules' has a description). The description adds some meaning by explaining lessons as 'title/description only' and implying that 'title' is the course title, but it does not cover the many other parameters (tags, difficulty, visibility, etc.) nor provide any syntax or format details. With such low coverage, the description should compensate more than it does.

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 'Scaffold' and names the exact resource scope: 'course + modules + lesson placeholders (title/description only, no content yet).' This clearly distinguishes it from sibling tools like hivelearn_create_course (which likely creates only a course) and hivelearn_create_lesson/module, by emphasizing the one-call combined creation.

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 context: 'This is the preferred first step when authoring a new course from a plan.' It also gives a direct follow-up instruction: 'loop over the returned lesson ids with hivelearn_update_lesson_content.' However, it does not state when NOT to use this tool or name alternative approaches (e.g., using hivelearn_create_course + create_module + create_lesson), so it lacks full exclusion guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does it well: it identifies the acting principal ('API key's owner'), states that the discussion is published and immediately visible to all members, and discloses that notification side-effect. It does not mention return values or modification/deletion behavior, but the core behavioral traits are disclosed.

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 efficient sentence with no filler. It front-loads the core action first and then adds the most decision-relevant behavioral consequences (visibility and notifications), making every clause informative.

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 description covers the action, actor, visibility, and notification effects, and the schema fully documents all parameters. However, there is no output schema and the description does not mention what the call returns, which is relevant context for a creation tool without annotation coverage.

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 documents all six parameters, including the title requirement and the content/content_json alternative. The tool description adds no parameter-level detail beyond the schema, which is the baseline situation for full schema coverage.

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 ('Start') and resource ('a discussion') and adds useful behavioral context: it is created as the API key's owner, published immediately, visible to all members, and triggers notifications. It does not explicitly compare itself to sibling tools like create_discussion_reply or create_post, but the resource and behavior are clear enough to identify its purpose.

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 should be used when the agent wants to start a discussion and broadcast it to members, which is reasonable guidance. However, it does not explicitly state when to prefer this tool over alternatives such as create_discussion_reply or create_post, nor does it mention any exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the reply is visible to all members immediately, notifies the discussion author, and fails with 409 if locked. It also explains the content_format default behavior. This is good behavioral disclosure for a mutation tool, though it doesn't mention reversibility or permissions.

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

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

Three sentences, each earning its place: the first states the core action and visibility, the second discloses the failure mode, the third explains the nesting parameter. No fluff, front-loaded with the primary purpose.

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 no annotations and no output schema, the description covers the key behavioral aspects: visibility, notification, lock failure, and nesting. It doesn't describe the response format, but the absence of an output schema makes that a minor gap. The 409 error is a valuable addition.

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 schema already documents all parameters. The description adds value by explaining the relationship between content and content_json (alternative bodies), the default content_format behavior, and the purpose of parent_reply_id (nesting). This goes beyond the schema's field descriptions.

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

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

The description clearly states the action ('Reply to a discussion'), the actor ('as the API key's owner'), and the resource. It distinguishes this from hivelearn_create_discussion (creating a new discussion) and hivelearn_list_discussion_replies (reading replies). The verb 'Reply' is specific and 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 provides clear context on when to use this tool: to reply to a discussion, with the ability to nest under another reply via parent_reply_id. It doesn't explicitly name alternatives or exclusions, but the sibling list makes the distinction obvious (create_discussion vs create_discussion_reply). The 409 lock failure is a useful usage constraint.

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

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

With no annotations, the description carries the transparency burden. It discloses two key behaviors: both IDs must belong to the authenticated community and duplicate enrollments are rejected. However, it does not mention return values, error handling, permissions, or side effects, leaving some behavioral ambiguity.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds meaningful information. No filler or redundant phrasing.

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

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

The tool is simple (two required UUID parameters) and the description covers the core purpose and two important constraints. It lacks mention of return value or error behavior, but those could be inferred from the action. Given the simplicity, it is mostly complete.

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

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

Schema coverage is 0%, so the description must compensate. It adds the community constraint for both user_id and course_id, which is helpful, but it does not individually explain the semantics of each parameter beyond their names. The tool name and first sentence already imply the roles, but the description could go further.

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 ('Enroll a user in a course') with a specific verb and resource, and it adds constraints (community membership, duplicate rejection) that distinguish it from sibling tools. This clearly separates it from create_course, create_certificate, and other create operations.

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

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

The description provides clear context for when to use the tool: to enroll a user in a course. It implies a prerequisite (community membership) and a constraint (duplicates rejected) but does not explicitly name alternative tools or state when not to use it. The context is sufficient for a straightforward creation tool with no direct sibling.

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

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

With no annotations, the description carries the burden and does disclose input format (ISO 8601, UTC) and the relationship between event_type, meeting_url, and location. However, it does not mention return values, side effects, or permission requirements.

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

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

The description is two sentences with no extraneous content. It front-loads the core purpose and provides essential details efficiently.

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 13-parameter tool with no output schema, this description is somewhat minimal. It covers the critical date and event_type logic, but ignores many optional fields and does not describe the response shape, leaving gaps for the agent.

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 description adds semantic value by specifying the UTC format for dates and explaining how event_type determines whether meeting_url or location is relevant. This compensates for the low schema coverage, though it leaves many optional parameters unexplained.

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 'Create a calendar event', using a specific verb and resource, and distinguishes it from other create_* siblings by specifying the domain. The additional detail about event_type further clarifies the tool's purpose.

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

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

The description implies usage for creating calendar events, but does not explicitly discuss when to use this tool over update_event or list_events. It does provide clear context for creation, but lacks exclusions or alternative recommendations.

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

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

With no annotations, the description carries the full burden. It discloses the constraint that content_type must match content_url and explains the module_id null behavior. However, it does not describe potential side effects, return values, authorization needs, or error conditions, leaving significant behavioral gaps for a create operation.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and extraneous detail, 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 13-parameter tool with no output schema and no annotations, the description covers the essential behavior but omits guidance on most optional parameters. It is adequate for a basic invocation but incomplete for a fully informed agent deciding on optional fields like content_format, is_published, or content_json.

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

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

Schema description coverage is only 8% (only is_preview has a description), so the description must compensate. It does add valuable meaning for the non-obvious parameters: content_type/content_url matching (with a concrete youtube example) and module_id null semantics. However, it does not explain other parameters like content_json, content_format, sort_order, or duration_seconds, which remain underspecified.

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's action and resource: 'Add a lesson to a course.' This specific verb+resource phrasing distinguishes it from sibling tools like create_module or update_lesson. The additional context about content_type matching and module assignment further clarifies its scope.

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

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

The description provides clear guidance on how to use the tool for key parameters (content_type must match content_url, module_id=null vs. a module uuid from list_course_modules). It references a sibling tool for valid module IDs. However, it does not explicitly state when to use this tool instead of alternatives like update_lesson or create_module, so it stops short of full when/when-not 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?

No annotations are provided, so the description carries the full burden. It adds the behavioral detail that the author is the API key's creator, which is valuable. However, it does not disclose other behaviors like whether the note is truly private (invisible to the member), idempotency, permissions required, or what happens on success. This is a gap given no annotations, so a 3.

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

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

The description is two concise sentences with no fluff. It front-loads the action and adds the key author behavior in the second sentence. Every word earns its place, so a 5.

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

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

For a simple create operation with two well-documented parameters and no output schema, the description is mostly sufficient. It clearly states the purpose and the author attribution. However, it does not mention what the tool returns on success or any potential errors, which could be useful. Given the low complexity, this is a minor gap, so a 4.

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 100% coverage with descriptions for both parameters, including the crucial clarification that user_id is the profile uuid, not the membership row id. The description adds no additional parameter semantics beyond what the schema already provides, so 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 clearly states the verb 'Add' and the resource 'private admin note to a member', which distinguishes it from list_member_notes and other create_* tools. It is specific and not a tautology. It lacks explicit differentiation from siblings, but there is no competing create-note tool, so a 4 is appropriate.

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 use case: when an admin wants to attach a note to a member. However, it does not explicitly state when to use this tool versus alternatives (e.g., when not to use it, or what other tools might be relevant). Since there is no direct alternative for creating member notes, the guidance is minimal but adequate, so a 3.

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

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

With no annotations, the description carries the full transparency burden. It discloses that names are unique per community and that duplicates trigger a 409 error, which is actionable behavioral information beyond the schema. It doesn't mention permissions or success response, but the key constraint is well covered.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the uniqueness constraint earns its place. Every word contributes to understanding.

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 description covers the core purpose and a key error condition, but with no output schema, it does not explain what a successful call returns (e.g., the created tag object or ID). This is a notable gap for an agent selecting and invoking the tool, though the tool's simplicity softens the impact.

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% as both parameters have descriptions. The description adds value by stating 'Names are unique per community,' which enriches the 'name' parameter semantics beyond the schema's simple 'Tag name.' This goes beyond the baseline 3 for good schema coverage.

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: 'Create a member tag.' It is specific and unambiguous, but it does not explicitly distinguish itself from sibling tools like hivelearn_add_member_tag, though the verb 'create' implies definition vs. assignment. This is clear but lacks an explicit sibling comparison.

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

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

The description implies usage: use this when you need to create a new tag. It provides no explicit when-to-use or when-not-to-use guidance, nor does it mention obvious alternatives like assigning existing tags via add_member_tag. Usage context is left mostly implicit.

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

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

With no annotations provided, the description carries the full burden. It discloses one behavioral trait: 'sort_order is optional — server auto-appends if omitted.' This is useful, but it omits other important behaviors such as return values, whether the course must exist, and any side effects on existing modules. Moderate transparency.

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, front-loaded with the main action. Every word earns its place, and it is appropriately sized for a simple create 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 basic create tool with 3 parameters and no output schema, the description is adequate: it states the purpose and the key optional behavior. However, it lacks details on what the tool returns, whether the course_id must reference an existing course, and how this relates to other module-focused tools. Complete enough for selection but not for full invocation context.

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 description adds semantic meaning for sort_order ('server auto-appends if omitted'), which the schema alone does not convey. However, it does not explain the meaning or format of course_id or title beyond their names, and schema description coverage is low at 0%. It partially compensates but leaves gaps.

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 'Add a module to a course' uses a specific verb (add) and resource (module to a course), clearly distinguishing it from sibling tools like create_lesson or create_course. It is unambiguous about the operation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., course must exist), nor does it contrast with creating lessons or other components. The usage context is only implied by the verb 'add'.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It does specify key constraints (content/content_json requirement, format matching, category default) but doesn't address edge cases like what happens if both content and content_json are supplied, or what the response/visibility implications of 'publish' are.

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 compact sentences, front-loaded with the primary action and then covering the essential constraints. Every sentence contributes value without repetition or fluff.

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 moderate-complexity create tool with no output schema and no annotations, the description covers the main usage rules (which fields, format matching, category) but omits edge cases and post-creation behavior. It is adequate for basic invocation but leaves some gaps in understanding the full behavior.

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 already describes content, content_json, and content_format, but the description adds the crucial exclusivity/requirement relationship and clarifies the category default ('general'). This meaningfully supplements the schema, especially for the undocumented category parameter.

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

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

The description opens with a specific action—'Publish a new post to the community feed'—clearly stating the resource (post) and the destination (community feed). This verb+resource+context combination distinguishes it from other create_* siblings and from update_post.

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 context for creation (a new post) and explains the required field relationship (either content or content_json) and the format-matching rule. It doesn't explicitly mention when not to use this tool or alternatives like update_post, but the creation context is unambiguous.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states the comment is visible to all members immediately, notifies the post author, and awards comment points, which goes far beyond a generic 'create' statement.

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

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

Three focused sentences with no filler. The core action is front-loaded, followed by key side effects and optional reply behavior, 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 description, combined with 100% schema description coverage, gives an agent everything needed to select and invoke the tool correctly. It covers the actor, effects, visibility, notification, points, and reply mechanics despite having no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates parent_comment_id semantics already present in the schema and adds no new parameter-level detail, but the schema adequately documents the remaining 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 uses a specific verb and resource: 'Comment on a feed post as the API key's owner.' It clearly distinguishes this tool from siblings like create_post and create_discussion_reply by specifying the feed-post context and the actor.

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

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

It provides clear context for when to use the tool: commenting on a feed post, with parent_comment_id guidance for replies. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the primary effect (creates an empty bank) but nothing else—no side effects, permissions, idempotency, or what happens on name conflicts. For a simple create operation, the minimal description conveys the essential behavior but leaves other behavioral aspects 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. It front-loads the purpose ('Create an empty question bank') and immediately provides actionable guidance for the next step (adding questions). Every sentence earns its place, and the structure is clean.

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

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

For a simple create tool with two scalar parameters and no output schema, the description covers the essential workflow by mentioning the empty state and pointing to the item tool. It doesn't describe return values, but that's optional given the lack of an output schema. The only minor gap is no mention of naming conventions or what the 'description' field is for, though these are inferable from 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?

The schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. However, the description does not mention the 'name' or 'description' parameters at all, nor their purpose or constraints. The parameter names are self-explanatory, but the description adds no value beyond what the schema already shows, failing to compensate for the coverage gap.

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

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

The description states a specific verb and resource: 'Create an empty question bank.' It distinguishes itself from the sibling hivelearn_create_question_bank_item by explicitly noting the bank starts empty and that questions are added via the item tool. This makes the tool's purpose immediately clear relative to its closest sibling.

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 this tool to create an empty question bank, then use hivelearn_create_question_bank_item to populate it. It names the explicit alternative for adding questions, which guides the agent's workflow. However, it doesn't mention any exclusions or when not to use this tool, such as when updating an existing bank might be more appropriate.

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

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

With no annotations, the description must carry the behavioral disclosure burden. It clearly implies a create/add operation and adds valuable conditional behavior (which answer field to supply per type). However, it does not disclose side effects, permissions, error conditions (e.g., invalid bank_id), idempotency, or what happens if multiple answer fields are supplied.

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 fluff and front-loads the core purpose. The parenthetical listing of type-to-field mappings is dense but efficient. It could benefit from a cleaner structure (e.g., a short list), but 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?

Given the tool's complexity (10 parameters, 6 question types, no output schema, no annotations), the description covers the most critical decision: which answer field to use for each type. It omits some operational context, such as how defaults like points behave or what happens when a bank is missing, but the core guidance needed to invoke the tool correctly 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?

Schema description coverage is 60%, so the description needs to compensate. It does exactly that by explicitly mapping question_type to the correct answer parameter (options, correct_answer, accepted_answers, pairs, items), which the schema only hints at via individual field descriptions. This adds meaningful semantic guidance beyond the raw schema.

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

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

The description states a specific verb and resource: 'Add a question to a bank.' It also enumerates all six question types, making the tool's scope unambiguous. The name and description clearly distinguish it from siblings like create_question_bank (which creates the bank itself) and create_quiz_question (which targets quizzes).

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

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

The description provides clear context for using the tool: it is for adding questions to a question bank and supports all six types. It gives per-type field instructions (e.g., options for multiple_choice) that guide correct usage. However, it does not explicitly state when not to use it or mention alternatives, such as update_question_bank_item for modifying existing items.

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

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

With no annotations, the description must carry the behavioral burden. It provides useful semantics (passing_score as percent, omitting time_limit_seconds/max_attempts for unlimited), but does not disclose permissions, side effects, or return value. This is reasonable but incomplete for a create operation.

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, front-loading the core purpose and then adding essential parameter semantics. Every word earns its place 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?

For a 7-parameter create tool with no output schema and no annotations, the description is adequate but not complete. It gives key parameter hints but misses return value, prerequisites, and deeper behavioral context, making it minimally viable.

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

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

Schema coverage is 0% and the description partially compensates by explaining passing_score range and the 'omit for unlimited' behavior for two parameters. However, it does not clarify title, lesson_id, description, or shuffle_questions, leaving gaps.

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 'Create a quiz attached to a lesson', which specifies the verb, resource, and attachment context. This distinguishes it from sibling tools like create_quiz_question and update_quiz.

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

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

The description implies usage for creating quizzes in a lesson context, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It offers some context ('attached to a lesson') but lacks direct comparison 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?

With no annotations, the description carries the burden of behavioral disclosure, and it clearly identifies the operation as adding a question. It also surfaces correctness constraints, such as exactly one is_correct for multiple_choice, but it does not disclose behavior on validation failure, whether the question is appended immediately, or what is returned.

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 dense sentence with no filler and it front-loads the purpose. The type-to-answer mapping is compact and scannable, though a short list or explicit bullet structure would slightly improve readability.

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

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

For a complex conditional create operation with no annotation support, the description covers the critical cross-parameter rules, namely which answer field to supply for each type, and leaves simpler optional parameters to the schema. It could add a note about response or error behavior, but the invocation-relevant information is largely 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 description maps each question_type to the required answer parameter and its shape, which is the most important semantic linkage beyond the schema. It does not restate every parameter, but it compensates for the moderate schema coverage on the conditional fields where misuse is most likely.

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

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

The description opens with a specific verb and resource: 'Add a question to a quiz.' It is clearly distinct from sibling create tools such as create_quiz or create_question_bank_item, and the target resource is unambiguous.

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

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

It gives strong conditional guidance for constructing the answer field per question_type, but it does not explicitly state when to choose this tool over alternatives like update_quiz_question, create_quiz, or create_question_bank_item. The intended use is implied by 'Add a question to a quiz' rather than explicitly contrasted.

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, it provides useful constraints: 'at least one is required' for resource_url/file_url, price > 0, and access_level defaults to public. However, it does not disclose other defaults (is_published, resource_type) or side effects, limiting transparency.

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

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

Two sentences, front-loaded with purpose, and every clause adds information. Extremely concise without sacrificing clarity.

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

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

For a 12-parameter tool with no output schema and no annotations, the description is somewhat thin. It covers key usage constraints but omits several default behaviors and parameter roles, making it adequate but not comprehensive.

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 roughly 50%, and the description adds meaning for a few parameters (e.g., the mutual exclusivity of resource_url/file_url, price positivity). But it ignores many parameters like folder_id, is_premium, or cover_image_url, so it only partially compensates for the schema gaps.

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 starts with a clear verb+resource: 'Add a resource to the community library.' This distinguishes it from sibling create tools like create_course or create_post, making its 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?

It implies usage for community library resources but does not explicitly mention when to prefer this tool over alternatives or state exclusions. The guidance on choosing between resource_url and file_url is parameter-level, not tool-level.

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

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

With no annotations provided, the description carries the safety and behavior disclosure burden. It reveals meaningful behavioral facts beyond the schema: duplicate sibling names produce a 409, parent folders must belong to the same community, and price cannot be zero or negative. It does not cover permissions, idempotency, or response behavior, but it does disclose the main failure conditions.

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

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

Three short sentences, each earning its place: the first states the action, the next two state the most important validation constraints. The key decision-relevant information is front-loaded and there is no redundant filler.

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

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

The description adequately captures the core creation rules for a folder, but the tool has 7 parameters, no annotations, and no output schema. It does not describe the response shape, the created folder's ID, permission prerequisites, or default behavior for unspecified fields. An agent can form a valid request but not fully predict what a successful call returns.

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 57%, so the schema covers some fields but not all. The description adds semantic value by explaining parent_folder_id scoping, name uniqueness, and the positive-price rule. These details go beyond the structured schema, particularly for name and the community constraint on folders.

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

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

The description opens with a specific verb and resource: 'Create a resource-library folder.' This distinguishes it from sibling create_* tools such as hivelearn_create_resource, hivelearn_create_course, and hivelearn_create_module, which target different entity types. The purpose is immediately clear and not a restatement of the tool name.

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

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

The description provides several important call constraints: parent_folder_id must be in the same community, names must be unique among siblings, and price must be positive. However, it does not explicitly state when to use this tool versus alternatives like hivelearn_create_resource or when to prefer updating an existing folder. Usage context is implied rather than directly contrasted.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the is_published default and advises deferring publication, but it does not mention the return value, required permissions, or any side effects beyond creation. This leaves some ambiguity about what the agent receives after calling the tool.

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

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

Three short sentences with no filler. The first sentence states purpose, the second gives the next action, and the third explains the default behavior. Every sentence earns its place.

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

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

The description covers the creation intent and the follow-up workflow, but because there is no output schema, it should explain what the tool returns—particularly since the track ID is presumably needed for hivelearn_add_track_course. It also leaves several parameters under-elaborated, making the overall guidance useful but incomplete.

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

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

Schema description coverage is only 14% (only is_published gets an inline description). The description repeats that default but leaves title, description, thumbnail_url, estimated_hours, and difficulty_level unexplained beyond their schema types and enum choices. The 'curated course sequence' phrase adds conceptual context but not per-parameter semantics.

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 'Create a learning track (curated course sequence)', clearly identifying the action and resource. It distinguishes from sibling tools by tagging hivelearn_add_track_course as the next step and separating 'track' from raw course creation.

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

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

It gives explicit workflow guidance: 'After this, add courses in order with hivelearn_add_track_course' and 'publish once the curriculum is set.' This directly instructs the agent on sequencing and when to set is_published, though it does not explicitly list when not to use the tool versus other create_* 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?

No annotations are present, so the description carries the full burden and delivers remarkably rich disclosure: credit cost (1 vs 5 with hybrid_chapters), paid-plan restriction, scope prerequisites, rate limits (2 running, 10 per hour), and source_type constraints (video_url accepts public links; other types require pre-uploaded media, external URLs rejected).

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?

Five sentences, each carrying exactly one distinct operational fact, with the core purpose and async flow front-loaded ahead of cost, scope, and rate-limit details. Zero 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 12-parameter async mutation with no annotations and no output schema, the description covers the entire risk surface: purpose, return mechanism (job_id → poll), cost, authorization scope, rate limits, and input restrictions. Nothing an agent needs to call it safely 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?

With only 50% schema coverage, the description compensates for the two required parameters and the cost-critical video_mode by explaining the video_url vs media-storage distinction and the 5-credit cost of hybrid_chapters. Remaining parameters (style_preset, content_depth, brand_intensity) gain no additional meaning, but the high-risk ones are covered.

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

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

States a specific verb and resource ('Generate a full course with AI') and immediately names the async counterpart (hivelearn_get_ai_job) that receives the returned job_id. This clearly distinguishes it from direct-creation siblings like hivelearn_create_course.

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?

Provides explicit operational guidance: confirm with the user before callingaving, and warns that the generate:ai_courses scope is required while admin:* does NOT include it. It doesn't explicitly name a non-AI alternative, but the job_id polling pattern plus the sibling set makes the usage context clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It clarifies whose balance is returned (the API key's creator), notes that purchased top-ups never expire, and discloses the required authorization scope (read:ai). These details go beyond the empty schema and give an agent actionable expectations about the operation's nature and requirements.

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

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

The description is a tight two-sentence block with no filler. The first sentence front-loads the resource and its key attributes, while the second efficiently adds the usage directive and authorization requirement. Every sentence earns its place, and the structure is highly scannable.

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 (zero parameters, no output schema, no annotations), the description is complete. It covers what the tool returns, whose data it reflects, when it should be called, and what authorization is needed. Nothing an agent needs to decide whether and how to invoke this tool is missing.

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

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

The tool has zero parameters with 100% schema coverage, so the baseline for parameter semantics is 4. There are no parameters to document, and the description adds value by outlining exactly what the response contains (allowance, top-ups, total, reset date, enabled flag), which helps an agent interpret the return value despite the lack of an output 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 the tool returns the AI credit balance for the API key's creator, explicitly listing the components: monthly allowance remaining, purchased top-ups, total available, reset date, and the AI Course Builder enabled flag. This specific verb+resource distinguishes it from all sibling get_* tools, particularly hivelearn_get_ai_job and the generation 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 instruction 'Check this before generating' provides a clear and explicit usage context, signaling the tool is a pre-flight check before AI generation. It also states the required scope (read:ai), acting as a prerequisite. However, it does not explicitly name the sibling generation tool or state when not to use it, 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?

With no annotations, the description carries full behavioral burden and does so well: it enumerates all five status values, explains current_step and course_id, and discloses the automatic failure/refund behavior for jobs stuck queued with started_at null, plus the required read:ai scope.

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

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

Three sentences with no filler. The core purpose and polling trigger are front-loaded, and every sentence adds information about statuses, stuck-job behavior, or 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 single-parameter polling tool with no output schema, the description covers the status model, the resulting course_id, timeout behavior, and authentication requirement. An agent has enough context to call it and interpret the response.

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

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

Schema coverage is 0%, so the description must compensate for the lone job_id parameter. It implies the source of the ID by saying to poll after hivelearn_generate_ai_course, but never explicitly states that job_id is the identifier returned by that call or by list_ai_jobs. The name is self-explanatory, but the provenance is left to inference.

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

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

The description opens with a specific verb and resource: 'Status and progress of one AI generation job.' It clearly differentiates from sibling list_ai_jobs by emphasizing 'one' job, and from generate_ai_course by framing it as the polling counterpart.

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

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

Explicitly instructs when to use it: 'Poll after hivelearn_generate_ai_course.' It also states the required scope. It does not explicitly describe when not to use it or name list_ai_jobs as the alternative for multiple jobs, 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?

With no annotations, the description carries the disclosure burden. It explicitly states the required permission (read:analytics), the trailing-window behavior with default 30, and the exact set of metrics included, and clarifies that definitions match the admin dashboard. It could go further on response shape or pagination, but for a read-only summary tool this is strong.

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 dense sentence that front-loads the purpose and window, then lists metric categories, dashboard alignment, and permission. Every clause adds useful information and there is no filler.

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

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

For a simple one-parameter read tool, the description covers the window, default, permission, and metric contents well enough to invoke it correctly. There is no output schema, and the description does not explicitly describe the response envelope, but the enumerated metric list gives a clear picture of what the summary includes.

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% for the single parameter, and the schema already documents days as a 1-365 trailing window with a default of 30. The description restates the default and trailing-window concept but adds no new parameter-level meaning beyond what the schema provides, so the 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 resource (community analytics) and a specific action (get summary over a trailing window), then enumerates the included metrics. This is enough to distinguish it from siblings like hivelearn_get_course_analytics and hivelearn_get_leaderboard without needing the schema.

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

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

No explicit guidance about when to choose this tool over alternatives. It notes the default time window and the read:analytics permission requirement, but does not say when to prefer this over course analytics, leaderboards, or other analytics-oriented 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?

No annotations are provided, so the description carries the burden. It discloses the required permission (read:courses) and describes the response content (text/url, status, instructor feedback, reviewer). It does not mention error behavior, but for a read operation this is adequate.

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

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

One sentence with no waste. The verb is front-loaded, the resource and returned fields are listed, and the permission is stated at the end.

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 fetch tool with one parameter and no output schema, the description covers the essential behavior: what it returns and what permission is needed. It could mention that the id is the submission id (already in schema) or that it returns a single object, but nothing critical 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 single parameter 'id' with description 'Submission uuid', so the description adds no extra parameter guidance. With 100% schema coverage, the baseline is 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?

States a specific verb ('Fetch'), a specific resource ('one assignment submission'), and enumerates the returned fields (text/url, status, instructor feedback, reviewer). It distinguishes itself from the sibling list_assignment_submissions (which fetches multiple) and grade_assignment_submission (which modifies).

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 this tool is for fetching a single submission by including 'one', and the sibling list tool is named differently. However, it does not explicitly state when to use this over list_assignment_submissions, nor does it mention alternatives. The context is clear but no exclusions are given.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Fetch' implies a safe read operation, and the mention of 'Includes verification_code and download URL' hints at the return content. However, it does not explicitly state error behavior, permissions, or any side effects, leaving gaps for a simple get tool.

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

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

The description is exceptionally concise and front-loaded, using two short sentences that convey the essential purpose and key return fields. There is no wasted verbiage, and the key information is immediately accessible.

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 low complexity (1 parameter, no annotations, no output schema), the description is largely complete: it states the operation, the parameter, and two useful fields in the response. It could be more complete by noting not-found behavior or explicitly stating read-only status, but these are minor gaps for a straightforward get-by-id tool.

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

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

The schema provides no description for the 'id' parameter (0% coverage), so the description must compensate. Saying 'by id' confirms the parameter's role, but it adds little beyond what the tool name and parameter name imply. It does not clarify the UUID format or other constraints already in the schema, so the added value is minimal.

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 'Fetch' and resource 'one certificate by id', which clearly states the tool's action and scope. It naturally distinguishes from sibling tools like list_certificates (which retrieves multiple) and verify_certificate (which verifies), making its 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 clearly indicates when to use this tool: when you need to fetch a single certificate by ID. However, it does not explicitly mention alternatives or exclusions, such as using list_certificates for multiple certificates, so it lacks the explicit when-not guidance needed for a 5.

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

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

With no annotations, the description carries the full burden. It discloses that the API key scopes the tenancy and that switching is not possible, which is important behavioral context. It also states the fields included in the return value, though it does not describe the full return shape or error behavior.

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

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

The description is two sentences, with the core purpose in the first sentence and usage guidance in the second. There is no filler, and it is immediately scannable.

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 tool with no output schema, the description is complete: it says what is returned, when to use it, and the key tenancy constraint. The agent has everything needed to select and invoke the tool correctly.

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

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

There are zero parameters, so the baseline is 4. The description adds valuable context by explaining that the API key itself determines the result, which clarifies why no parameters are needed. This goes beyond the empty schema.

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

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

The description clearly identifies the tool's function with the verb 'Returns' and specifies the exact resource: 'the community the current API key is scoped to'. It also lists the key fields returned (community_id, owner, slug, tier), which distinguishes it from any sibling tool.

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

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

It explicitly states when to use the tool: 'Use this first whenever you need the community_id, owner, slug, or tier'. It also explains the API key determines tenancy and that you cannot switch community. It lacks an explicit 'when not to use' clause, but no sibling tool competes for this same purpose.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns metadata and implies it does not return the lesson tree by pointing to the sibling. It also lists specific return fields, adding behavioral context beyond a simple 'get' call, though it omits error handling or auth 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 two sentences with no filler. The first sentence defines purpose and key fields, the second gives a precise alternative. It is front-loaded and efficient, with every word earning its place.

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

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

For a single-parameter read tool with no output schema or annotations, the description covers the main purpose and alternative but lacks details on response format, error handling, or parameter specifics. It is adequate for basic selection but not fully complete for an agent requiring comprehensive context.

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

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

Schema description coverage is 0%, and the description does not explain the 'id' parameter at all. It only implies that the id identifies the course, but fails to clarify the special UUID patterns or how to obtain the id, thus not compensating for the low schema coverage.

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 'Fetch' with a clear resource 'one course' and lists the metadata fields (description, instructor, tags, flags). It explicitly distinguishes itself from the sibling tool hivelearn_get_course_structure, 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?

It provides direct usage guidance by stating 'For the lesson tree use hivelearn_get_course_structure instead,' which clearly tells the agent when not to use this tool and which alternative to choose. This is an explicit exclusion and alternative reference.

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

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

With no annotations, the description carries the behavioral burden. It discloses pagination, sort order, the trailing-window time scope, and the required 'read:analytics' permission, which signals this is a safe read operation. It does not detail response shape or error behavior, but the core behavior is transparent.

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

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

The description is a single compact block that front-loads the resource and scope, lists metrics efficiently, and ends with two short sentences on pagination and permissions. Every phrase earns its place; nothing is redundant or missing.

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 paginated analytics tool with no output schema, the description provides enough orientation: metrics, ordering, pagination, and permissions. It could be slightly stronger by stating the response container or pagination metadata, but an agent has sufficient information to call and interpret the tool.

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

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

Schema coverage is 100%, and the description only adds a small mapping by referencing the `days` window. Since the schema already documents days, limit, and offset with defaults and ranges, the description does not need to add much; 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 uses a specific verb and resource ('Per-course analytics') and clearly states the scope ('for the community'), ordering ('newest course first'), and the exact metrics returned. This distinguishes it from the sibling get_analytics_summary without needing to inspect 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?

It conveys clear context: per-course analytics, a trailing window in days, pagination, and the required read:analytics permission. It does not explicitly name alternatives or exclusion conditions, but 'per-course' strongly implies when this tool is appropriate versus summary-level 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes what data is returned but does not explicitly state that this is a read-only operation, nor does it mention pagination, error behavior, or any side effects. For a get tool, this lack of safety or traversal detail is a notable gap.

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

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

The description is two short sentences, front-loaded with the core purpose and a usage hint. Every word earns its place; there is no repetition of schema field names or obvious fluff.

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

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

With 4 parameters, no output schema, and zero annotations, the description is too brief to be fully actionable. It does not mention pagination (despite limit/offset parameters), response structure, or how 'pass/fail' is represented. For a tool of this complexity, the description should provide more context about the returned data and query behavior.

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

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

Schema description coverage is only 50% (limit and offset have descriptions, course_id and user_id do not). The description adds some meaning by mentioning 'per-user' (user_id) and 'for a course' (course_id), but it does not explain limit/offset beyond what the schema already provides. Overall, the description does not fully compensate for the missing schema descriptions.

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 resource as a quiz-score gradebook for a course, specifying per-user attempts, scores, and pass/fail status. This distinguishes it from any sibling tool, as no other gradebook tool exists. The verb 'get' is implicit in the name, and the description conveys the exact data scope.

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 'Use for analytics or grading dashboards,' providing clear context for when this tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, though the unique gradebook purpose makes alternatives less relevant.

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

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

With no annotations, the description carries the burden of disclosing behavior. It does disclose return fields (percent_complete, last_accessed_at, completed_lesson_count) and the aggregate nature, but omits details like pagination semantics, whether user_id filters to a single user, sorting behavior, or any access constraints. 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 concise sentences, front-loaded with a clear verb and resource. The first sentence states the action and scope; the second lists the return fields. No filler or redundant information.

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

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

For a get-type tool with 4 parameters and no output schema, the description covers the essential purpose and return shape. It adequately explains that results are per-user rows, which is critical. Gaps include lack of ordering/pagination context and clarification of the user_id optionality, but these are minor given the simple nature of the tool.

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

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

Schema description coverage is high (75%), so the baseline is 3. The description adds some context beyond the schema by mentioning 'per-user' and 'course', but it does not clarify the course_id parameter (which lacks a schema description) or the optional user_id filter behavior. It adds marginal value over the structured data.

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's function with a specific verb ('Aggregate') and resource ('lesson-completion progress for a course across enrolled users'), immediately distinguishing it from sibling progress tools like hivelearn_get_track_progress. It also lists the key returned fields, leaving no ambiguity about purpose.

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

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

The description provides clear context for when to use the tool: aggregating lesson-completion progress for a course across enrolled users. It does not explicitly mention alternatives or exclusions, but the context is strong enough to differentiate from similar tools like get_course_gradebook or get_enrollment.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals the output is a compact tree with only titles, and explicitly states what is excluded (lesson body content). This gives useful behavioral insight, though it does not cover all possible aspects like error handling or permissions.

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 concise with two sentences. The first sentence states the core function, the second provides use cases and a key limitation. No unnecessary words are used, and it is 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?

The tool is simple with a single parameter and no output schema. The description explains the return structure at a high level (course → modules → lessons) and notes the exclusion of body content. This is sufficient for the tool's complexity, though a bit more detail on node structure would be helpful.

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

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

The schema has one parameter (id) with 0% description coverage. The description does not explicitly explain the parameter, but the phrase 'of the course' and the tool name imply that the id refers to a course. While not fully compensating, the parameter's meaning is largely self-evident, so a mid-range score 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 tool returns a 'compact titles-only tree of the course: course → modules → lessons', which is a specific verb and resource. It also distinguishes itself by explicitly noting it does NOT include lesson body content, separating it from sibling tools like get_lesson or list_course_lessons.

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

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

The description provides clear usage context by saying it is 'Ideal for agents to plan reorders, spot empty lessons, or summarize a course'. It does not explicitly mention alternatives or when not to use it, but the intended scenarios are clearly stated.

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

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

With no annotations provided, the description carries the behavioral burden. It does disclose a read-like retrieval action and an author-inclusion behavior, but it says nothing about not-found handling, permissions, or response shape. For a simple fetch 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, deeply front-loaded: the core purpose appears first, and the sibling routing appears second. 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 single-parameter fetch tool, the description plus schema covers the essential invocation context: what to fetch, how to identify it, and how to get replies. A small gap remains around not-found behavior and what the full returned discussion object contains, but overall it is sufficient for an agent to select and call the tool.

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

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

Schema coverage is 100%, so the schema already documents the sole parameter, including its UUID format and source (from list_discussions). The description's 'by uuid' adds no meaning 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 identifies the action ('Fetch'), the resource ('one discussion'), and the lookup key ('by uuid'). It also distinguishes this from list-style siblings by scope, and the phrase 'with author' adds a specific return expectation.

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 second sentence explicitly directs the agent to the appropriate alternative: 'Use list_discussion_replies for its replies.' This tells the agent when to use a sibling instead, which is clear, actionable guidance.

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

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

With no annotations, the description carries the full burden. It discloses the return content (status and progress) and the action (fetch), implying read-only behavior. However, it does not mention error behavior, permissions, or side effects, which would add risk 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 a single sentence with no redundant words. It is front-loaded with the action and resource, making it highly concise and scannable.

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 get-by-ID tool with one parameter and no output schema, the description provides sufficient context about the return (status and progress). It could be more complete by mentioning not-found behavior or permissions, but given the tool's simplicity, it covers the essentials.

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

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

The schema has 0% description coverage for the single 'id' parameter. The description adds meaning by clarifying that the ID refers to an enrollment ('one enrollment'), but it does not explicitly state 'the enrollment ID' or provide format details beyond the schema's UUID pattern.

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 ('Fetch'), states the resource ('one enrollment'), and includes scope ('with status and progress'). It clearly distinguishes this from sibling tools like list_enrollments by indicating it fetches a single enrollment.

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

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

The description implies usage for fetching a single enrollment by ID, but does not explicitly state when to prefer this over list_enrollments or mention alternatives. It is clear enough for the reader to infer, but lacks explicit 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?

No annotations are provided, so the description carries the burden. It discloses that the response includes full description and RSVP metadata, giving some insight into return value. However, it does not mention potential errors, authorization needs, or any other behavioral traits beyond the core fetch action. The read-only nature is implied by 'Fetch' but not explicitly stated.

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 one concise sentence that immediately states the action and resource. It contains no fluff and every word adds value, making it highly 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?

The tool has a single simple parameter, no output schema, and no annotations. The description covers the core functionality and indicates the response content (full description and RSVP metadata). It is sufficiently complete for such a straightforward get-by-id tool, though it could mention the return format or error behavior for full 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 has only one parameter (id) with format details, and schema description coverage is 0%. The description clarifies that the id refers to an event, which adds semantic meaning, but it does not provide additional details about the parameter itself. Given the simplicity of the single parameter, a 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 'Fetch' with a clear resource ('one event') and identifier ('by id'), and distinguishes the action from sibling tools like list_events or create_event by specifying the retrieval of a single event with additional context. It clearly communicates the tool's scope and purpose.

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 a single event's full details are needed by id) but does not explicitly exclude alternatives like list_events. It provides clear context without stating when-not-to-use or naming alternatives, which places it at a strong 4.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does add value by disclosing that each entry contains 'rank and the points for the selected period, plus level info,' and explains period windows. However, it does not explicitly state that this is a read-only operation, nor does it clarify pagination behavior or ordering direction beyond 'ranked.'

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

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

The description is two sentences, front-loaded with the tool's purpose. Every sentence provides useful information: the resource, the period windows, and the response entry structure. No unnecessary words or repetition.

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 tool with three self-explanatory parameters and no output schema, the description is quite complete. It covers purpose, response contents, and period semantics. However, it could be marginally more complete by explicitly noting that pagination via limit/offset applies and that the operation is read-only, though these are implied by the parameter schema and the tool name.

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 baseline is 3. The description adds some semantic context by explaining that 'period chooses the window' and that points are 'for the selected period,' which complements the schema's enum. However, it does not add further detail for limit or offset beyond the schema descriptions.

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's purpose: 'Ranked member leaderboard for the community.' It uses a specific verb ('get') and resource ('leaderboard'), and distinguishes it from other tools by describing the leaderboard specific to the community. The period options are explicitly mentioned, further clarifying its functionality.

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

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

The description implies usage for retrieving a community leaderboard and explains the period parameter window, but it does not explicitly state when to use this tool over alternatives or provide any exclusions. Sibling tools like get_member_points exist but are not referenced, leaving the guidance implicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the return format ('same fields as list_members for one row') and implies a read-only 'fetch' operation, but it does not disclose error behavior, whether the member must exist, or any authorization requirements. It adds some context beyond the schema but leaves gaps.

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, front-loaded with the action, and every clause contributes: it specifies the identifier and clarifies the output shape by referencing list_members. No unnecessary words or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context by linking the return fields to list_members. However, it omits behavior for not-found cases or errors, which would make it fully complete. For a simple fetch, this is a minor gap.

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

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

Schema description coverage is 100%; the parameter 'id' already has a detailed description, format, and pattern. The tool description simply restates 'profile uuid' and references list_members, which adds marginal value but essentially duplicates schema information. 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 the action ('Fetch a single member'), the resource ('member'), and the method ('by profile uuid'). It distinguishes from sibling tools like list_members (by emphasizing 'single' vs. the list) and get_member_points (by the resource being member, not points).

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 this tool: when you need one member identified by profile uuid. It also clarifies the output is a single row with same fields as list_members, which suggests using this instead of list_members for a specific member. However, it doesn't explicitly mention alternatives or exclusions for edge cases.

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

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

With no annotations provided, the description carries the full burden, and it does disclose one genuinely useful behavioral trait: the tool returns 404 until the daily job has scored the member. However, it offers nothing else about return shape, auth requirements, or what the score represents beyond the parenthetical, leaving room for more detail for an unannotated tool.

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

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

Two sentences with zero waste: the primary purpose is front-loaded in the first sentencechers, and the second sentence delivers the critical 404 caveat. 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 one-parameter read tool, the description covers the operation, the score's components, and the timing quirk that would otherwise surprise callers. The only notable gap is no description of the response shape, which matters a bit more given there is no output schema.

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

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

Schema description coverage is 100%, and the schema already clarifies the key nuance (user/profile UUID, not membership row id). The tool description adds no parameter-level information, so the 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 names a specific verb and resource ('Get a member's health score') and immediately enumerates what the score covers (engagement, activity, risk level), which disambiguates it from siblings like get_member and get_member_points. The parenthetical removes ambiguity about what 'health' means.

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 given on when to use this tool versus alternatives such as get_member, get_member_points, or get_course_progress. The daily-job timing note implies freshness constraints but does not state when an agent should prefer this tool or what to do when the 404 occurs.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly mentions the 404 error case for members without a points record, and clarifies the lookup key ('by auth user id'). It does not discuss rate limits or auth, but for a read-only get operation, this is solid disclosure.

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

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

The description is two sentences with no filler. The first sentence front-loads the key information and enumerates the output components; the second adds the error condition. 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 single-parameter get tool with no output schema, the description spells out the return fields and the 404 behavior. It does not explain the meaning of 'period totals' or the community context, but that is minor for this simple tool. The description is essentially complete for the agent to select and invoke it.

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

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

Schema coverage is 100% and the schema already describes user_id as 'auth user id (community_members.user_id)'. The description reinforces this by saying 'by auth user id' but adds little new meaning about the parameter itself. Baseline 3 is appropriate given the schema covers it fully.

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 ('get') and resource ('member points'), enumerating the exact contents (total, per-category, period totals, level). It distinguishes from siblings like get_member (profile) and get_leaderboard (ranking) by detailing the breakdown.

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 context is clear: this is for retrieving a full points breakdown for one member. It does not explicitly mention alternatives or when-not-to-use, but the specialized scope and the 404 condition effectively convey its purpose. No exclusions are stated, so this remains a clear if not exhaustive guideline.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a key trait: the reply thread is not included, which is valuable. However, it does not mention auth requirements, return format, or error handling, so transparency is partial but adequate for a simple fetch operation.

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

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

The description is two short sentences with the verb and resource front-loaded. Every word earns its place, and the exclusion note is concise and informative 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?

For a single-resource get tool with one parameter and no output schema, the description is fairly complete. It specifies what is returned (full post content) and what is not (reply thread), covering the essential usage context. Minor omissions like error conditions are acceptable for such a simple tool.

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

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

The schema provides the 'id' parameter with a UUID format but no description. The description's phrase 'Fetch one post' makes it obvious that 'id' refers to the post identifier, effectively compensating for the 0% schema description coverage. This is sufficient for a single self-evident parameter.

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 ('Fetch') and resource ('one post'), clearly distinguishing it from list operations like hivelearn_list_posts. The phrase 'with full content' adds specificity about what is retrieved, making the tool's purpose unmistakable.

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 this tool is for retrieving a single post's full content, and the explicit note that the reply thread is NOT included helps prevent misuse when a thread is needed. It does not name an alternative sibling tool, but the implied usage context is clear and the exclusion note provides practical 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?

No annotations are provided, so the description carries the behavioral burden. It discloses two useful traits: the response includes item_count and does not include the items themselves. It does not describe error behavior, permissions, or whether the count is live, but as a simple fetch operation it is adequately transparent for most agent use.

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 primary purpose is front-loaded, and the pointer to the sibling tool is placed second, keeping the highest-value information first.

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 definition is complete enough for a single-id fetch: it states what is returned, what is not returned, and how to get the omitted items. It would be stronger with an explicit note on not-found behavior or a fuller description of the question bank object, but it covers the core invocation context.

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

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

The schema has 0% description coverage and only one required 'id' parameter with a UUID format. The description implies that 'id' identifies the question bank being fetched, but it does not add explicit parameter-level semantics. For a single, self-evident identifier this is sufficient, though not richly explanatory.

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 ('Fetch one question bank') and adds a distinctive detail ('with its item_count'), which separates it from list-style siblings. It also explicitly names the related item-listing tool, eliminating ambiguity between this and hivelearn_list_question_bank_items.

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 routes the agent to hivelearn_list_question_bank_items when the items themselves are needed, which is helpful usage guidance. However, it does not explicitly contrast this with hivelearn_list_question_banks, so the when-to-use guidance is slightly incomplete.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It adds important context about what is not included (questions) and what metadata fields to expect, but it does not disclose error behavior, authentication requirements, or return format beyond the listed fields.

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

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

The description is a single, front-loaded sentence that immediately states the primary action and resource, then adds one clarifying exclusion and a concrete alternative. Every word earns its place, with no redundant information.

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

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

Given the low complexity (one parameter, no output schema), the description covers the key aspects: what is returned, what is not returned, and where to go for the missing part. It falls short only in omitting possible error/not-found behavior, but for a simple get-by-id tool this is a minor gap.

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

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

The schema has one 'id' parameter with no description (0% coverage). The tool description does not explicitly explain that 'id' refers to the quiz ID, though the tool name and 'Fetch one quiz' make it inferable. This is minimally sufficient but does not fully compensate for the missing schema description.

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

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

The description uses a specific verb 'Fetch' with a clear resource 'one quiz' and enumerates the included metadata (passing_score, time_limit, max_attempts). It also explicitly differentiates from sibling tools by stating questions are not included and naming the alternative tool.

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

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

The description clearly indicates when to use the tool (fetching a single quiz's metadata) and provides an explicit when-not-to-use scenario by stating questions are excluded and pointing to hivelearn_list_quiz_questions. It does not mention using hivelearn_list_quizzes for fetching multiple quizzes, but the 'one quiz' phrasing implies the distinction.

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

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

No annotations are present, so the description carries the transparency burden. It discloses key behaviors: only published resources are returned, 404 is returned for unpublished or cross-community resources, and the author is joined. This is substantial, though it omits details like authentication requirements or return format.

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, well-structured sentence that front-loads the action and resource. It includes essential behavioral notes without unnecessary verbosity.

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 getter with one parameter and no output schema, the description covers the core functionality, success condition, and error condition. It is not exhaustive but sufficient for an agent to select and invoke the tool correctly. The absence of alternative guidance is a minor gap.

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

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

Schema description coverage is 0%, and the description only restates 'by id' without adding meaning beyond the schema's own id property name and UUID format. The description does not compensate for the lack of parameter documentation.

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

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

The description clearly identifies the tool as fetching a single published resource by ID, with the joined author. It distinguishes from siblings by specifying 'published' and the 404 condition, making its scope precise.

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

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

The description implies usage for retrieving one resource by ID, and the 404 behavior clarifies when not to use it. However, it does not explicitly mention alternatives like list_resources for listing, nor does it state when to prefer this over other getters.

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

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

With no annotations, the description carries the behavioral burden. It discloses a non-obvious failure mode ('404 if it belongs to another community') and the presence of resource_count in the result. It does not mention authentication or other error cases, but for a simple one-parameter getter this is reasonably transparent.

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

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

Two concise sentences with no unnecessary words. The core action and the key edge case are front-loaded, making the description easy to scan and act on.

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 getter with no output schema, the description covers the lookup target, the included resource_count field, and the community-scoping 404 behavior. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description adds only minimal meaning: the id identifies the resource folder to fetch. It correctly links the sole required parameter to the operation but does not elaborate beyond what the schema already implies.

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?

Description uses a specific verb and resource: 'Fetch one resource folder by id, with its resource_count.' It clearly distinguishes from siblings like list_resource_folders (one vs list) and get_resource (folder vs resource). The 404 clause reinforces the tool's specific scope.

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?

'Fetch one resource folder by id' clearly signals the use case of single-item lookup by ID, implying that list_resource_folders is the choice for multiple folders. It does not explicitly name alternatives or state when not to use the tool, but the context is clear enough for an agent.

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

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

No annotations are provided, so the description must carry the full burden. It only says 'with full metadata'—a vague term—and does not disclose auth requirements, rate limits, error cases, or what exactly 'full metadata' includes. The read-only nature is implied by 'fetch' but not explicitly stated.

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 with no filler. The first sentence states the action, the second provides a crucial alternative. 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 get-by-id tool, the description covers the essential purpose and the main alternative. However, without an output schema, the phrase 'full metadata' is vague and could leave the agent uncertain about the return structure. Still, the tool is simple and the description is largely 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 only parameter is 'id', and the description clarifies it refers to the track id via 'by id.' However, with 0% schema coverage, the description adds no extra detail about the parameter (e.g., format, constraints), though the schema already provides format and pattern. It is adequate but not compensating beyond the obvious.

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?

'Fetch one learning track by id with full metadata' uses a specific verb and resource, clearly distinguishing it from related tools. The reference to 'ordered curriculum' differentiates it from hivelearn_list_track_courses.

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

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

The description explicitly states when to use this tool (to fetch a single track's metadata) and provides a direct alternative: 'For its ordered curriculum use hivelearn_list_track_courses.' This is clear and actionable.

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

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

No annotations are provided, so the description carries the full burden of behavioral transparency. It discloses what data is returned but does not state whether the operation is read-only, what authentication or permissions are required, or any rate limits or error behavior. For a retrieval tool, this lack of explicit non-mutating guarantee is a gap.

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

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

The description is compact and front-loaded with the tool's purpose, followed by a usage suggestion. Every sentence contributes: the first defines what the tool returns, the second gives context. There is no repetition of schema constraints.

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

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

With no output schema and no annotations, the description needs to explain the return shape and safety profile. It lists key output fields but not the full response structure (e.g., whether it's a list object with pagination metadata). It also does not state the read-only nature of the operation. However, the tool is relatively simple, and the schema covers pagination parameters. This is adequate-but-gapped.

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 documents limit and offset with descriptions (67% coverage), but track_id has no description. The description implies track_id is the track of interest ('through a learning track') but does not add detail about UUID format or behavior. It also does not explain pagination behavior beyond what schema already says.

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 this tool returns per-member progress through a learning track, enumerating specific fields (enrolled_at, started_at, completed_at, total_courses, completed counts). This differentiates it from the sibling get_course_progress, which is presumably per-course. The verb ('get') is implied by the tool name, and the resource (track progress) is explicit.

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

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

The description provides a clear use case ('cohort/track analytics'), which helps the agent decide when to invoke it. However, it does not explicitly name alternative tools for course-level progress, such as hivelearn_get_course_progress, nor does it state when not to use it. This is clear context without exclusions.

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

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

With no annotations, the description carries the full disclosure burden, and it does well: it reveals that the action is attributed to the API key's creator, that it mutates a member's record and is visible to the student, and that revision_requested requires feedback. It omits return-value and idempotency details, but for a mutation tool the disclosed side effects and constraints are substantial.

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 compact and front-loaded, with every sentence earning its place: action, side effects, conditional requirement, and permission. There is no fluff or repetition of schema contents beyond what is useful for behavioral clarity.

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

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

For a three-parameter tool with no output schema and no annotations, the description covers the essential calling context: purpose, required status values, visible side effects, attribution, permission, and the feedback requirement. It does not describe the return value or the precise semantics of each status, but these are less critical given the clear enum and mutation focus.

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 already documents id and feedback, and the status enum lists valid values, so the baseline is moderate. The description adds real value beyond the schema by specifying the cross-parameter rule that revision_requested requires feedback, and it clarifies that feedback is instructor feedback shown to the student. This is more than a restatement of properties.

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

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

The description opens with a specific verb and resource ('Review an assignment submission') and then enumerates exactly what the tool does: sets a status and instructor feedback. It clearly differentiates this from the read-only siblings like hivelearn_get_assignment_submission and hivelearn_list_assignment_submissions by stating that it changes a member's record and the student will see the change.

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 solid usage context: it is for reviewing/grading a submission, it mutates visible state, and it requires the write:grades permission. It does not explicitly name alternatives or say when not to use it, but the context is strong enough that an agent should know this is the grading action rather than a retrieval 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds useful details: newest-first ordering, included status/progress fields, and the required read scope. However, it does not describe pagination behavior, empty-result behavior, or any other response characteristics beyond those fields.

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

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

The description is one efficient sentence that front-loads the verb and resource, then adds ordering, output fields, and an access requirement. No wasted words.

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

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

For a simple list operation with two optional parameters, the description is largely complete: it states what is listed, the ordering, key output fields, and required scope. A small gap is that 'key creator's' is somewhat ambiguous and no return structure is described, but the tool is simple enough that this is not 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning about limit or offset beyond what the schema already 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?

The description clearly states the verb 'List' and the resource: the key creator's AI course generation jobs in the community, with ordering ('newest first') and included fields ('status and progress'). It is distinct enough from the singular sibling hivelearn_get_ai_job, though it does not explicitly name that sibling.

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

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

The description provides clear context for use: it lists AI course generation jobs, sorted newest first, and notes the required 'read:ai' scope. It does not explicitly mention when to prefer this over hivelearn_get_ai_job, but the list-versus-single distinction is reasonably clear.

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

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

With no annotations, the description carries the behavioral burden. It discloses the required permission ('Requires read:courses'), the result ordering, and returned fields. However, it does not mention pagination/limit-offset handling (beyond the schema), any access scoping rules, or potential absence of results when no filters are supplied.

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 zero filler. The core purpose and scope are front-loaded, followed by filters and a permission requirement. 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?

Provides purpose, ordering, filters, and permission, which covers the essentials for a read-only list tool. Missing explicit pagination behavior (page size default, skipping) and a clear statement that all filters are optional, though limit/offset schema descriptions offer some guidance. No output schema exists, so the mention of returned fields ('student profile and lesson title') is useful but minimal.

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 40% (only limit and offset have descriptions). The description adds semantics for status, course_id, and lesson_id by labeling them as filters, which is helpful but does not explain each parameter's role in detail or that filters are optional. It partially compensates for the low coverage.

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 ('List'), resource ('assignment submissions'), scope ('in the community'), ordering ('newest first'), and included data ('student profile and lesson title'). It clearly distinguishes from siblings like get_assignment_submission (singular fetch) and grade_assignment_submission (grading 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 mentions filtering by course_id, lesson_id, or status, which implies when to use those parameters, but it does not explicitly state when to prefer this list tool over the singular get_assignment_submission or provide exclusion criteria. Usage context is clear but alternatives are not addressed.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does mention return fields and optional scoping, but it omits behavioral traits such as default ordering, whether results are sorted by issued_at, and whether status is filterable. The phrase 'issued certificates' is slightly ambiguous regarding whether it includes all statuses or only 'issued' status. This is a minimum-viable disclosure but lacks depth.

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, information-dense sentence that front-loads the verb and resource, lists filter options, and enumerates return fields. Every word earns its place with 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 list tool with optional filters and no output schema, the description provides essential information: return fields, filter semantics, and the list operation itself. It does not explicitly state pagination defaults or how filters combine, but the schema covers pagination and the description's 'optionally scoped' implies flexibility. Overall, it is nearly complete for common usage scenarios.

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 description adds meaning to the user_id and course_id parameters by explaining they scope results ('scoped to one user or one course'). The limit and offset parameters are not mentioned, but the schema descriptions for them are explicit (page size, rows to skip). With 50% schema coverage, the description compensates for the filter parameters, which are the core semantic aspects.

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

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

The description clearly states the action ('List issued certificates') and the resource, with optional scoping to user or course. It also enumerates return fields, distinguishing it from siblings like get_certificate and verify_certificate. The verb + resource + scoping is specific and 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 provides clear context for when to use the tool: listing certificates, optionally filtered by one user or one course. It does not explicitly name alternatives or exclusions, but the scoping language effectively communicates the intended use cases. Sibling names imply alternatives (e.g., get_certificate for single retrieval), but the description itself stops short of explicit when-not guidance.

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

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

With no annotations provided, the description must carry the behavioral burden. It discloses that this tool returns a flat list (as opposed to a nested tree) and that it optionally filters by module, which are important behavioral traits. However, it does not mention pagination, ordering, or error behavior. Still, for a simple list operation, this is reasonably transparent and exceeds the minimum.

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 exceptionally concise: two short sentences that front-load the action and include a valuable alternative pointer. Every word earns its place, with 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 tool with only two parameters, no annotations, and no output schema, the description provides sufficient context. It tells the agent what the tool does, how to optionally restrict scope, and when to use a sibling tool instead. This covers the essential selection and invocation requirements for a list operation.

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

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

Schema description coverage is 0%, so the description should compensate. It adds meaning to module_id by stating 'optionally filtered to one module,' which clarifies its role as a filter. However, course_id is only implicit from the tool name and required status, and no extra detail is given about parameter formats or relationships. This is modest compensation for the lack of schema description.

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

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

The description clearly states the tool's function: 'List lessons of a course, optionally filtered to one module.' It uses a specific verb ('List'), identifies the resource (lessons of a course), and clarifies scope (optionally filtered to one module). It also distinguishes itself from sibling tool hivelearn_get_course_structure by pointing out that the latter provides a nested tree.

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 usage guidance: 'Use hivelearn_get_course_structure for a nested tree' implicitly tells the agent to use this tool for flat lists. It also mentions the optional module filtering, clarifying when that parameter is relevant. This gives clear context for choosing between this and a key alternative.

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

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

With no annotations provided, the description carries the full burden. It discloses the ordering behavior ('ordered by sort_order') and the domain relationship ('Modules group lessons; a course has 1..N modules'), which are useful. However, it does not mention safety (e.g., read-only), auth requirements, errors, or pagination, leaving some behavioral traits 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 extremely concise: two sentences, no fluff, and front-loaded with the purpose. Every phrase adds value—'List modules (sections)' defines what, 'ordered by sort_order' adds behavioral detail, and the second sentence provides domain context. This is an exemplary concise structure.

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

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

For a simple one-parameter list tool, the description covers the core purpose and ordering. However, there is no output schema, so the description should explain return values but does not mention what the module list contains (e.g., fields, pagination). The parameter semantics are also weak. The description provides enough for basic understanding but leaves gaps in expected output and parameter handling.

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

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

The schema has 0% description coverage, and the description does not explain the course_id parameter beyond saying 'of a course.' It does not name course_id or add any detail about its format, purpose, or constraints, leaving the agent to infer the mapping from the tool name alone. This is insufficient compensation for the schema's lack of description.

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

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

The description clearly states the tool's function: 'List modules (sections) of a course, ordered by sort_order.' It uses a specific verb ('List') and resource ('modules (sections) of a course'), and adds the ordering detail. It also distinguishes from siblings like list_course_lessons by explaining that modules group lessons, 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 usage by stating that modules group lessons and a course has 1..N modules, which helps an agent understand when to use this tool. However, it does not explicitly mention alternatives (e.g., list_course_lessons, get_course_structure) or provide when-not-to-use guidance, so the usage context is only implied rather than fully explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently lists the returned fields and explains the status parameter's behavioral implications (published = visible to learners), which is valuable. It does not mention pagination behavior or error handling, but the schema covers the parameters and the read-only nature is implied by 'List'.

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 long, with the main action front-loaded. It includes the most important filter behavior and return fields without any filler or redundant content, making it highly concise 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?

Despite lacking an output schema and annotations, the description covers the key return fields, the authentication scope, and the behavioral significance of the status filter. For a straightforward list operation, this is sufficient for an agent to understand what the tool does and what to expect, with only minor omissions like sorting or error scenarios that are not critical for selection.

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 all three parameters, so the baseline is 3. The description adds semantic value by explaining that status=published returns only courses visible to learners, which enriches the enum meaning. It also indicates the return fields, which provides additional context beyond 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 the tool lists courses in the authenticated community, with a specific verb ('List') and resource ('courses'). It distinguishes from sibling tools like get_course (single course) and create_course by implying a collection operation. The status clarification adds specificity to the purpose.

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

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

The description provides clear context for when to use the tool (listing courses) and explains the status=published filter's effect on learner visibility, guiding selection. However, it does not explicitly mention alternatives like get_course for single-course retrieval or exclusions, so it falls short of full guidance.

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

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

With no annotations, the description carries the full burden. It discloses the return shape and sort order, and the verb 'List' implies a non-destructive operation. It stops short of explicitly stating side-effect-free behavior or auth requirements, but for a simple read-only list endpoint this is adequate.

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

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

The description is two short sentences that front-load the action and ordering, followed by a compact list of return fields. Every sentence earns its place with no filler.

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

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

The description covers the essential context: what is returned and in what order, which is especially important since no output schema exists. Pagination is handled by the parameter schema, and the only required input is clear from 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%, and id, limit, and offset are already documented. The description adds no parameter-level details, so 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 uses a specific verb ('List') and a clear resource ('replies in a discussion'), adds the ordering detail ('oldest first'), and names the returned fields. This clearly differentiates it from siblings like create_discussion_reply and list_discussions.

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 the tool's scenario (listing replies in a discussion), so an agent can infer when to use it. However, it does not explicitly compare against alternative tools or state when not to use it, so usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden. It discloses ordering behavior and the exact fields returned, which is useful. However, it does not explicitly state that this is a read-only operation, how pagination works beyond the default in the schema, or whether content is truncated. It gives some behavioral context but not a full picture.

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, efficient sentence that front-loads the operation ('List published discussions'), clarifies the ordering, and enumerates returned fields. Every word earns its place with no filler or repetition.

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 list tool with three optional, fully documented parameters and no output schema, the description provides the necessary context: scope, ordering, and return fields. It lacks an explicit note about being read-only, but 'List' plus the schema and return field list make the operation clear. Minor gaps remain around pagination behavior and result count, but the schema covers defaults.

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 each parameter. The description adds nothing beyond the schema for 'limit', 'offset', or 'category' — the baseline of 3 applies because the schema does the heavy lifting and the description doesn't need to compensate.

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 ('List') and resource ('published discussions (forum threads)'), and adds meaningful distinctions: ordering ('pinned first then newest') and the return fields. This clearly separates it from get_discussion, create_discussion, and list_discussion_replies.

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

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

No explicit guidance is given about when to use this tool versus alternatives. There is no mention of when not to use it, no reference to a more filtered or detailed sibling, and no context about draft vs. published states beyond the word 'published'. The description implies usage but does not actively route an agent.

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

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

With no annotations, the description carries the burden. It discloses the returned fields and scoping options, which adds value. However, it does not explicitly state that this is a read-only operation (implied by 'List'), nor does it explain filter combination behavior or pagination semantics beyond what the schema provides. It 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 concise sentences: the first states the action and optional scoping, the second lists return fields. No wasted words, front-loaded with the core purpose.

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 list tool, the description covers purpose, scoping, and return values. Pagination parameters are already in the schema. It lacks explicit distinction from get_enrollment and filter semantics, but overall is fairly complete 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?

The schema describes limit and offset, but not user_id and course_id. The description adds meaning by saying 'scoped to one course or one user', mapping these parameters to filters. However, it does not clarify whether both can be used together or how they interact. Overall, it partially compensates for the 50% schema coverage gap.

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

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

The description uses a specific verb ('List') plus resource ('course enrollments') and clearly indicates optional scoping by course or user. This distinguishes it from siblings like get_enrollment (single enrollment) and create_enrollment.

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

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

The description implies usage: it's the list endpoint for enrollments, with optional filters. However, it does not explicitly mention alternatives such as get_enrollment for a single enrollment, nor does it state when not to use this tool. The context is clear but lacks exclusions.

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