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

With no annotations, the description must disclose behavioral traits. It only describes the action without mentioning side effects (e.g., replacing a previously accepted answer), permission requirements, reversibility, or validations. This is a significant gap for a mutating action.

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: two sentences plus a structured Args block. Purpose is front-loaded, and every sentence adds value. No redundant or filler 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?

The description covers the workflow and parameter provenance, and an output schema exists to document return values. However, it lacks behavioral specifics (side effects, authorization) and edge-case guidance, leaving it merely adequate for a two-parameter mutation tool.

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

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

The schema provides only integer types with no descriptions. The description compensates by explaining that thread_id comes from list_threads/search_threads and comment_id comes from get_thread. This adds practical meaning but does not cover constraints like comment belonging to thread.

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: 'Mark a comment as the accepted answer on a question thread.' This uses a specific verb and resource, and distinguishes it from sibling tools like mark_duplicate, endorse_thread, or lock_thread. The intent 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?

The description provides explicit workflow guidance: 'Use get_thread first to find the comment_id of the correct answer.' It also tells where to source thread_id and comment_id. However, it does not explicitly mention when not to use this tool or compare it to alternatives like endorse_thread.

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 dry_run behavior (preview without applying) and the need for pre-existing IDs/names, but does not mention whether changes are reversible, what side effects occur, or what the response looks like. For a mutating operation, this is adequate but not rich in behavioral detail.

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

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

The description is well-structured: an opening sentence states the core purpose, followed by prerequisite hints and an Args list. It is concise without being terse, but the Args section somewhat duplicates the schema; still, every sentence provides useful context.

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

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

Given the tool's moderate complexity (4 parameters, batch operation) and the presence of an output schema (not shown), the description covers the key aspects: what it does, how to obtain required inputs, and the optional dry-run behavior. It lacks explicit error-handling or edge-case discussion, but the guidance to use list_categories for valid names mitigates this. Overall, it is complete for a typical user.

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

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

Schema description coverage is 0%, so the description must compensate. It does so with an Args: list that explains each parameter: thread_ids (global thread IDs), category (use list_categories), subcategory (optional), and dry_run (preview vs apply). This adds meaning beyond the schema's titles and type, though it could provide more detail on constraints like minimum/maximum array size.

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

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

The description clearly states that the tool moves multiple threads to a new category at once, using a specific verb ('Move'), resource ('threads'), and scope ('multiple... at once'). This distinguishes it from sibling tools like delete_thread or lock_thread, and the batch nature 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 gives concrete guidance on how to use the tool: it directs users to search_threads/list_threads for thread IDs and list_categories for valid category names, and mentions dry_run for previewing. It implies the tool is for bulk operations but does not explicitly contrast with alternatives like edit_thread for single-thread changes, 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 provided, the description carries the full burden of behavioral disclosure. It mentions that 'start' defaults to now and that is_hidden hides the session from students, but it does not disclose permissions required, whether creation is reversible, or potential side effects like duplicate sessions. The tool's behavior is mostly opaque.

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 and front-loaded with the one-line purpose. The Args section is well-structured with each parameter on its own line, and every sentence adds value. It loses one point because the 'Args:' block is a somewhat verbose format for what could be more compact, but it remains clear and efficient.

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

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

The tool has a simple create semantics and an output schema, so return value explanations are not needed. The description provides sufficient parameter guidance and a prerequisite hint (list_courses), but it does not mention permissions, error conditions, or relationship to other actions. It feels minimally adequate but not rich in 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 significant meaning beyond the schema, which has 0% parameter descriptions. It explains course_id with a lookup hint, gives a title example, specifies the ISO 8601 format for start with a concrete example and default behavior, and clarifies that is_hidden controls student visibility. This covers all four parameters comprehensively.

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: 'Create a new attendance session in a course.' It uses a specific verb (create) and resource (attendance session), and the verb distinguishes it from sibling tools like update_attendance_session and delete_attendance_session.

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

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

The description gives a useful hint for looking up course_id via list_courses, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The usage is implied by the create action, but no exclusions or conditions are provided.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful behaviors: content must be wrapped in Ed XML, type determines thread kind, is_private hides from non-staff, and is_anonymous hides the author. However, it omits potential prerequisites like permissions, error behavior, and reversibility—common gaps for a mutation 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 well-structured: a one-sentence summary, a crucial content-format instruction, and a clean parameter list. Every line adds value without redundancy. It is longer than minimal but earns its length through dense, useful 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 creation tool with 8 parameters and no schema descriptions, the description covers the essentials: content construction, parameter lookups, type semantics, and privacy options. Since an output schema exists, omitting return values is acceptable. Missing permission and error-handling details are minor gaps, not fatal for this kind of tool.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining every parameter. It gives concrete guidance: content format with an XML example, valid type values, how to find course_id/category via other tools, and explicit meanings for the boolean flags. This goes well beyond the schema's type/default info.

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 new thread in a course,' a specific verb and resource. It clearly differentiates from sibling tools like delete_thread, lock_thread, and edit_thread by focusing on creation. It also clarifies the thread types and content format.

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 clear usage context: use list_categories for valid category names and list_courses for course_id. It explains the different thread types (post, question, announcement) and optional parameters. No exclusions or alternatives are given, but there is no other thread-creation 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 transparently discloses the destructive nature of the operation ('This cannot be undone') and the scope ('and all its check-ins'). It lacks details on permissions or other side effects, but the key behavioral traits are 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 exceptionally concise, with two short sentences for the operation and one line for the parameter. It is front-loaded with the essential action and consequence, containing no extraneous 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 simple delete tool with one parameter and an output schema present, the description completely covers the necessary context: the outcome, the scope, and the parameter source. No further explanation is needed.

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 significant meaning to the lone parameter event_id by explaining it is the session ID obtained from list_attendance_sessions results. This goes beyond the bare schema (integer, required) and provides actionable guidance.

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 ('Permanently delete') and resource ('attendance session and all its check-ins'). This distinguishes it from sibling tools like delete_thread or delete_comment.

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 by specifying the source of the event_id ('from list_attendance_sessions results') and warns about irreversibility. It does not explicitly name alternatives, but the context is sufficient for an agent to infer when this tool is 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?

No annotations are provided, so the description carries the burden of disclosing behavior. It explicitly states 'Permanently delete' and 'This cannot be undone,' which covers the most critical behavioral trait (irreversibility). It does not mention cascade effects or permissions, but for a simple delete 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?

The description is extremely concise: two sentences plus an args block. It front-loads the action and irreversible warning, with no filler or redundancy.

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

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

For a single-parameter delete operation, the description is complete. It explains the effect, irreversibility, and parameter origin. The presence of an output schema covers return value expectations, so no further detail is needed.

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 only provides the parameter name and type (integer), while the description adds crucial context: 'The comment ID (from get_thread results).' This fully explains the source and purpose of the parameter, compensating for the 0% schema description 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 exactly what the tool does with a specific verb and resource: 'Permanently delete a comment.' It clearly distinguishes from sibling tools like delete_thread and edit_comment by naming the resource (comment).

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 by noting the comment ID comes from get_thread results, implying when to use this tool. It does not explicitly state when not to use it or mention alternatives, but the purpose is straightforward enough that this is a minor gap.

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

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

No annotations are present, so the description carries the full burden. It discloses that the operation is irreversible ('This cannot be undone') and deletes comments plus the thread, which is critical safety information for a destructive action. It doesn't mention permissions or response values, but the output schema covers response; the core behavioral traits are 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 two sentences plus an Args line; the purpose and risk are stated first, and every word earns its place. No filler or redundant restatement of the schema.

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

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

For a one-parameter destructive tool with an output schema, the description covers the action, scope, irreversibility, and parameter source. This is sufficient to invoke correctly and understand consequences. The presence of an output schema means return values don't need to be described.

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 only gives thread_id as an integer, leaving 0% coverage, so the description must add semantics. It explains that thread_id is the global thread ID and specifies how to obtain it (list_threads or search_threads), which is valuable beyond the raw schema. This fully compensates for the schema gap.

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

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

The tool name and description clearly state it permanently deletes a thread and all its comments, specifying the resource (thread) and action (delete). It differentiates from delete_comment by covering cascading deletion of comments. This is a specific verb+resource description.

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 thread_id should come from list_threads or search_threads, giving a clear prerequisite for when to use. It doesn't explicitly contrast with alternatives like delete_comment or edit_thread, but the deletion scope ('all its comments') implies when this tool is appropriate. Context is clear enough for selection, though no explicit 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 burden of disclosure. It explains that the file is downloaded to a temporary local path and returns that path for reading/viewing. This covers key behavioral aspects, though it doesn't detail cleanup, failure modes, or file type handling.

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 well-structured. The first sentence states the purpose and result, and the second provides the parameter detail. No unnecessary words 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?

The tool is simple with one parameter and an output schema present. The description explains the return value and use case. It could mention edge cases like non-existent URLs or authentication, but for the tool's complexity it is sufficiently complete.

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

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

The input schema only names the parameter, but the description provides a clear definition and example ('The Ed CDN URL, e.g., https://static.au.edusercontent.com/files/...'), which fully compensates for the 0% 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 clearly states a specific action ('Download a file'), a specific resource ('Ed Discussion CDN URL'), and the output ('local file path'). This distinguishes it from sibling tools like upload_file and download_thread_files by specifying the source and destination.

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: when you have a CDN URL and need to read/view the file locally. However, it does not explicitly mention when to avoid this tool or compare it to alternatives like download_thread_files, so guidance is implied rather than direct.

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 files are downloaded to temporary local files and that local file paths are returned for reading/viewing. However, it does not mention permissions, cleanup behavior, or potential side effects like large downloads, leaving some behavioral 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 concise and well-structured: a clear action sentence followed by an Args block. Every sentence adds value without 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 one-parameter tool with an output schema, the description adequately covers what the tool does, what it returns, and where to get the input. The output schema handles return structure details, making the description sufficiently 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 single parameter thread_id is enriched by the description, which explains it is the global thread ID and points to where to find it (list_threads or search_threads results). This goes beyond the bare schema title 'Thread Id' and compensates for the 0% schema description 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 clearly states the tool downloads all images and file attachments from a thread's content, answers, and comments to temporary local files. It distinguishes itself from the sibling 'download_file' by specifying the batch scope and source (thread vs single file).

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: use when you need all thread attachments, and instructs the agent to obtain thread_id from list_threads or search_threads results. It does not explicitly name alternatives or exclusions, but the scope is evident from the description.

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 key behavioral trait that the entire body is replaced with new content in Ed XML format, which is important. However, it doesn't mention permissions, reversibility, or what happens on invalid input or non-existent comments.

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 paragraphs, front-loaded with the main purpose, followed by a concise arg list. Every sentence adds value with no redundant or filler 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?

The tool is simple with two params and has an output schema, so the description doesn't need to explain return values. It covers the core functionality and argument semantics adequately. Minor gaps like error handling or prerequisites beyond ID source are not critical for this simple mutation.

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

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

Schema coverage is 0%, but the description compensates well. It explains comment_id as 'from get_thread results' and defines content as 'New body in Ed XML format', adding meaningful context beyond the raw schema types. It could provide more details on constraints, but it sufficiently clarifies parameter purpose.

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 'Edit an existing comment's content' with a specific verb and resource, and further clarifies it replaces the entire body. This distinguishes it from siblings like delete_comment and edit_thread by specifying comment content modification.

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 saying 'Edit an existing comment's content' and notes the comment_id comes from get_thread results, but it doesn't explicitly state when to use this over alternatives or provide exclusions. Some context is given, but no alternative tools are mentioned.

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 does disclose key behavioral traits: partial updates ('Only provided fields are updated; omitted fields are left unchanged'), content format requirement ('Ed XML format'), and category validation via list_categories. It stops short of mentioning permission/error behavior, but the disclosed behaviors are significant for correct invocation.

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 followed by a structured Args block. Every line adds value, and the format makes the parameter behaviors easy to scan without 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 mutation tool with five parameters and no annotations, the description covers partial-update behavior, content format, valid category sources, and thread_id prerequisites. An output schema exists, so explanations of return values are unnecessary; this is a complete, self-sufficient description.

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 Args section comprehensively explains each parameter beyond the schema: thread_id is sourced from list_threads/search_threads, optional fields are described as 'omit to keep current,' and content must be in Ed XML format. This fully compensates for the 0% schema description 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 opens with 'Edit an existing thread's title, content, or category,' which gives a specific action, resource, and affected fields. This clearly distinguishes it from sibling tools like delete_thread or lock_thread, and the resource 'thread' separates it from edit_comment.

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: editing an existing thread, with thread_id obtained from list_threads or search_threads. It does not explicitly state alternatives or exclusions (e.g., 'use edit_comment for comments'), but the focus on threads is unambiguous enough for typical usage.

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 clearly indicates this is a mutating action ('Endorse a thread with an instructor badge'), which at least warns the agent. However, it doesn't disclose side effects, permissions (e.g., instructor-only), reversibility, or behavior when the thread is already endorsed. It adds some context but lacks depth for a no-annotation 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 short sentences plus an Args line. It is immediately clear what the tool does, and the parameter explanation is compact. No extraneous 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?

For a single-parameter tool, the description covers the core purpose and parameter well. It lacks usage alternatives and side-effect details, but given the simplicity and the presence of an output schema, it is reasonably complete. It could be improved by mentioning reversibility or related actions, but it's not fully inadequate.

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 only describes thread_id as an integer, but the description adds meaningful context: it's a global thread ID and can be obtained from list_threads or search_threads. This compensates well for the 0% schema description coverage, giving the agent actionable guidance.

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 'Endorse' and the thread resource, and explains the specific purpose: adding an instructor badge to signal good content or correctness. It distinguishes itself from siblings by specifying the badge context, which differs from unendorse_thread, accept_answer, and pin_thread.

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

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

The purpose ('to signal it contains good content or a correct answer') implies when to use it, but it does not explicitly mention alternatives or situations to avoid. There's no reference to siblings like accept_answer or unendorse_thread, so the guidance is implicit 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 provided, the description carries the full burden. It discloses the comprehensive scope ('all sessions with all check-ins') but does not elaborate on side effects, permissions, or potential performance implications. The read-only nature is implied by 'get' but not explicitly affirmed.

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: two sentences plus an Args block. The first sentence front-loads the core purpose and scope, the second gives a use case, and the Args block provides actionable parameter guidance. Every sentence adds value 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?

The tool is simple (one parameter) and has an output schema, so the description need not spell out return structure. It fully captures the purpose, the scope of data included, and how to obtain the required parameter. It is complete for correct selection and invocation.

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

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

The schema itself only says course_id is an integer with no description. The tool description adds meaningful guidance: it clarifies what the parameter represents and directs the user to list_courses to find it. For a single parameter, this compensates well for the 0% 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 clearly states the action ('Get') and the resource ('a combined attendance report for a course — all sessions with all check-ins'). It distinguishes this tool from siblings like list_attendance_sessions and list_check_ins by emphasizing the combined nature, and mentions its utility for summaries.

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

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

The phrase 'Useful for generating attendance summaries' provides a clear context for when to use this tool. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of full 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 of disclosing behavior. It states the return scope ('full details... including its check-ins') and that the parameter is a session ID, but does not explicitly note read-only behavior, error handling (e.g., invalid/nonexistent session), or any permissions. 'Get' implies read-only, but no further behavioral details are given.

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 very concise: a single sentence stating the action and an Args section with one line for the parameter. Every word earns its place, and the most important information is front-loaded.

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

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

The tool is simple with one required parameter, and an output schema exists so return values are not needed in the description. The description provides the purpose, the parameter's meaning/source, and what is included. It could have mentioned edge cases (e.g., what happens if the session is not found) but for a getter this is nearly 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 schema has no descriptions and 0% coverage, so the description must compensate. It does so effectively by clarifying that the parameter 'event_id' is actually the session ID and that it should be obtained from list_attendance_sessions results. This fully disambiguates the parameter name mismatch and provides necessary context.

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 ('Get') with a clear resource ('attendance session') and states it includes 'full details' and 'its check-ins'. This distinguishes it from sibling tools like list_check_ins, which focus only on check-ins, and from analytics tools like get_attendance_analytics.

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 a sequence: first call list_attendance_sessions to get the event_id, then call this tool. It provides clear context on when to use it (get details for a specific session) but does not explicitly exclude alternatives or mention when not to use it (e.g., for check-ins only). This is clear enough but not 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?

No annotations are provided, so the description carries the full burden. It states what the tool returns ('Returns enrollment count, number of unanswered questions...'), which implies a read-only aggregation with no side effects. However, it does not explicitly mention that it is non-destructive, nor does it mention permissions, error behavior, or potential performance implications. The description gives a reasonable but not exhaustive behavioral 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 concise and front-loaded: a one-sentence purpose, then a bullet-like list of return values, then a minimal Args section. Every sentence earns its place, with no redundancy or fluff. The structure makes it easy 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 simple read-only stats tool with one parameter and an output schema, the description covers purpose, usage context, parameter semantics, and return values. It even provides a cross-reference for finding the course ID. There are no significant gaps given the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the only parameter, course_id, and adds a cross-reference: 'use list_courses to find it.' This is highly valuable for an agent because it tells how to obtain the required identifier, going beyond the schema's bare integer type.

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: 'Get a quick course overview for daily review.' It lists specific metrics (enrollment count, unanswered questions, unresolved threads, new follow-up replies, top categories), which distinguishes it from sibling tools like get_enrollment_counts or list_threads. The verb 'get' and resource 'course stats' are 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 provides explicit usage context: 'for daily review.' This implies a high-level summary use case and differentiates it from more detailed or targeted tools, though it does not explicitly name alternatives or state when not to use. The guidance is clear enough for an agent to select it appropriately.

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 disclose behavior itself. It clearly states it is a read operation ('Read a thread') and mentions the return content ('Returns full content, comments, and answers'). This is sufficient for a simple get tool, though it does not cover edge cases like auth requirements or error handling, which are not expected to be exhaustive here.

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

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

The description is two concise sentences plus a structured args list. The first sentence front-loads the core purpose, and each part adds value (usage guidance, parameter explanations) without 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 has an output schema, so return values are presumably covered by that. The description covers the parameters and use case adequately, and the low complexity of a read-only get operation means no additional explanation is necessary. It is complete for a tool with these characteristics.

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 fully compensates. For course_id it adds 'use list_courses to find it', and for thread_number it clarifies 'as shown in the UI (e.g. 42 for thread #42)', giving concrete examples and preventing confusion with internal IDs.

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 'Read a thread by its number as shown in the Ed UI (e.g. #42, #220)', using a specific verb and resource and clearly identifying the unique method (by thread number). This distinguishes it from siblings like get_thread and get_thread_by_url, which likely use different identifiers.

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 'Use this when someone refers to a thread by number', providing clear use-case context. It also instructs to use list_courses to find the course_id. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses that this is a lightweight, quick operation that returns only aggregate counts, implying a read-only action. However, it does not explicitly state that it never writes data or what happens when the course_id is invalid. For a simple read tool, this is adequate but not fully transparent about edge cases.

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 paragraphs: the first states purpose and usage guidelines, the second defines the parameter. Every sentence earns its place, with no redundancy or filler. The key information is front-loaded.

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

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

Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers all essential aspects: purpose, return value, usage context, and parameter guidance. It also points to list_courses for finding valid IDs, which is helpful in the broader tool ecosystem. No critical gaps remain.

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 only defines course_id as an integer with no description. The description adds 'The course ID (use list_courses to find it),' which explains the parameter and how to obtain it. With 0% schema coverage, this compensation is valuable and materially helps the agent use the tool correctly.

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 'Get a quick headcount for a course' and specifies 'Returns student count and total enrolled.' This is a specific verb+resource with clear scope and return. It also distinguishes itself from list_users by calling itself 'quick' and 'without loading the full user list.'

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: 'Use this to answer "how many students" questions without loading the full user list.' It also provides an alternative: 'For per-role breakdowns (staff, admin), use list_users with a role filter.' This gives clear when-to-use and when-to-use-a-different-tool 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. It clearly indicates a read-only operation via the verb 'Read' and explains the crucial distinction between global thread ID and UI number to prevent misuse. This gives the agent the necessary behavioral context without 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 efficient and well-organized: it opens with the core purpose, follows with usage context and an alternative, then defines the argument. Every sentence carries value, with no redundancy or excessive length.

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 simple interface (one parameter), an output schema, and clear context. The description covers purpose, when to use, alternative, and parameter semantics. Given the output schema exists, return values need not be described. This is complete for a read 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?

The schema only defines thread_id as an integer with no description. The description's Args section fully compensates by explaining that it is a large number from list_threads/search_threads, not the UI #number. This adds essential meaning 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 begins with 'Read a thread's full content, comments, and answers,' which clearly specifies the verb, resource, and scope. It also distinguishes itself from sibling tools like get_course_thread by clarifying the ID type, 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 explicitly states when to use: 'Use this when you have a thread ID (a large number like 2785693) from list_threads or search_threads results.' It also provides an alternative: 'For looking up a thread by its UI number (e.g. #42), use get_course_thread instead.' This is clear guidance with a named 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 of behavioral disclosure. It does state that the operation is a 'Read' and that it returns content, comments, and answers, which is useful. However, it does not detail authentication requirements, error handling, or edge cases (e.g., invalid URLs, permissions). For a read-only tool, 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 extremely concise and well-structured. The first sentence states the action, the second gives a clear when-to-use trigger, and the Args section provides parameter details. Every sentence earns its place with 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 simple one-parameter read tool, the description is nearly complete. It specifies the input format, the intended use case, and the return value (content, comments, answers). Since an output schema exists, the description does not need to detail the response structure. It lacks only minor details like rate limits or auth scopes, but these are not critical for this 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 has no description for the 'url' parameter (0% coverage), so the description must compensate. It does so excellently by defining the parameter as 'Full Ed Discussion thread URL' and providing a realistic example. This fully clarifies the expected input format and meaning, leaving no ambiguity.

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 reads a thread from an Ed Discussion URL. It uses a specific verb ('Read') and resource ('thread by URL'), and distinguishes itself from siblings by emphasizing the URL-based retrieval mechanism, which is unique among tools like get_thread or get_course_thread.

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 for when to use the tool: 'Use this when someone shares a link to a thread.' This is clear and actionable, though it does not explicitly exclude alternative tools or provide a when-not-to-use scenario. The close sibling get_thread likely accepts an ID, so this URL-based tool fills a distinct niche, but the description could have explicitly contrasted them.

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?

Although no annotations are provided, the description adds important behavioral context by specifying that this returns the 'authenticated user's' profile, not arbitrary users. It also lists visible fields (name, role). However, it does not explicitly mention safety (read-only), authentication requirements, or error behavior, which would push it to a 5.

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 sentences, front-loaded with the primary purpose, followed by a direct reference to an alternative. Every word earns its place, with 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?

Given the tool's simplicity (zero parameters, output schema present), the description is fully complete. It states what it returns, clarifies the scope (authenticated user), and provides the key alternative. No critical operational detail is missing for this simple profile-fetch 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?

The tool has zero parameters, so the baseline is 4 as per rubric. The description adds no parameter-specific details because there are none, but it does clarify the scope of the returned profile, which is useful context.

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: 'Get the authenticated user's profile (name, role).' It also explicitly differentiates from sibling tool list_courses by directing users to that tool for enrolled courses, 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 provides explicit usage guidance by stating 'Call list_courses instead to see enrolled courses.' This tells the agent exactly when to use this tool versus the alternative, satisfying the 'when-to-use vs alternatives' criterion.

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 explains that the tool retrieves a user's posts and comments, and describes the filtering and pagination behavior. While it doesn't explicitly state read-only, the verb 'See' and context imply it, and no side effects are mentioned.

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 and well-structured: a one-sentence summary followed by a minimal Args block. Every line adds value (parameter explanations, defaults, filter values), and there is no redundant repetition of the schema.

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 has 5 parameters and an output schema, the description provides the essential context: purpose, required IDs, pagination, and filtering. It doesn't discuss result ordering or edge cases, but for a straightforward retrieval tool, it is sufficiently complete.

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

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

The input schema has no descriptions (0% coverage), and the description compensates fully by explaining each parameter: user_id and course_id with lookup guidance, limit and offset for pagination, and filter with specific allowed values. This adds significant meaning 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 clearly states the tool's purpose: 'See what a specific user has been posting and commenting in a course.' This is a specific verb (see) and resource (specific user activity), and it distinguishes itself from sibling tools like get_user (profile info) and list_users (listing users).

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 on when to use the tool: it requires user_id and course_id, and explicitly says 'Use list_users first to find the user_id' and 'Use list_courses to find the course_id.' It does not explicitly mention alternatives or when not to use it, but the preconditions are 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?

No annotations are provided, so the description carries the full burden. It does disclose that the output consists of compact summaries, which is a useful behavioral trait. However, it lacks explicit mention of auth requirements, side effects (if any), or read-only guarantees, though the verb 'list' implicitly suggests safety. The transparency 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?

The description is concise and well-structured: the opening sentence states the action, the second clarifies the output nature, the third provides an alternative, and the Args section offers parameter guidance without unnecessary fluff. Every sentence earns its place.

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

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

For a simple list operation with one parameter and an output schema, the description covers purpose, output format, an alternative for full details, and parameter discovery. It is complete enough 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?

The input schema only defines course_id as an integer with no description, and schema description coverage is 0%. The description compensates fully by explaining course_id is the course ID and telling the agent to use list_courses to find it, adding meaningful domain 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 it lists attendance sessions for a course, using a specific verb and resource. It also distinguishes from the sibling get_attendance_session by noting it returns compact summaries, which is a key 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 explicitly directs the agent to use get_attendance_session when full details are needed, and lists list_courses as a prerequisite for finding course_id. This provides clear context and a named alternative, satisfying the 'when vs. alternative' requirement.

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 convey behavioral traits on its own. The verb 'List' implies a read-only operation, and the description adds purpose, but it does not explicitly state whether the operation is safe, what side effects (if any) exist, or whether permissions are required. For a simple read operation, 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?

The description is two sentences plus a brief parameter note, with no wasted words. The main purpose is front-loaded, and the structure (description followed by Args) is clean and easy to scan.

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 a single parameter and an output schema, the description provides all necessary context: what it lists, why to use it, and how to use the parameter. The output schema covers return values, so no further explanation is needed.

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

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

The input schema provides only type and requirement, with no description for course_id. The description compensates fully by explaining the parameter's meaning and how to find it, explicitly referencing list_courses. This is clear and actionable.

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: listing thread categories and subcategories for a course. The verb 'List' plus the specific resource 'thread categories and subcategories' is specific and distinguishes it from siblings that manage threads themselves.

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 says to use this tool to find valid category names before creating or recategorising threads, which provides clear usage context. It does not mention exclusions or alternative tools for the same purpose, but it does reference list_courses for finding the course ID, offering relevant contextual 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 must carry the transparency burden. It explains how results are scoped by course or event, but does not explicitly state that this is a read-only operation, nor does it clarify behavior when both parameters are provided or when neither is provided. The 'List' verb implies non-mutation but the edge cases remain unaddressed.

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: one opening sentence plus a short arg list. No filler or redundant information. The structure front-loads the purpose and then gives parameter details in an easily scannable format.

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 (2 optional params, no nested objects) and presence of an output schema, the description covers the main use cases clearly. However, it leaves gaps around edge cases (both/neither param) and does not address pagination or result ordering, which would be useful for a list tool.

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

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

Schema description coverage is 0%, so the description compensates by explaining the meaning and impact of each parameter: course_id returns check-ins across all sessions, event_id returns only that session's check-ins. It does not mention that both are optional or what happens if combined, but the core semantics are well 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?

The description 'List attendance check-ins' uses a specific verb and resource, and clearly distinguishes between two scopes: all check-ins across sessions (course_id) and a single session (event_id). This separates it from sibling tools like list_attendance_sessions and get_attendance_session.

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 each parameter: course_id for course-wide check-ins, event_id for a specific session. However, it does not explicitly name alternatives or state when not to use this tool, only implying the choice via parameter semantics.

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 the user-specific scope and the exact return fields (id, code, name, year, session, status). It does not explicitly state that it is read-only or mention pagination, but the list operation is evident from the verb and field 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 front-loaded with the purpose and followed by a clearly structured Args block. Every sentence adds value, with no redundancy or unnecessary detail.

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

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

The output schema exists, so the description need not explain return structure, but it still names key fields. It also provides usage context and filter semantics, making it complete for a list 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 has zero parameter descriptions, but the description fully compensates by explaining each parameter: status with allowed values, year with an example, and code as a case-insensitive substring. This adds substantial meaning 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 'List courses the user is enrolled in' and positions the tool as the entry point for finding course_id, distinguishing it from sibling list tools like list_users or list_categories.

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 instructs 'Call this first to find a course_id before using other tools,' providing strong when-to-use guidance. It also explains filter semantics with omission behavior, though it does not name alternative 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 the tool returns compact summaries (no full content), that invalid filter values silently return empty results, and that it is a fallback browse tool. It could additionally mention read-only behavior or permission requirements, but for a listing operation this level of disclosure is solid.

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 well-structured: it front-loads the most critical usage guidance (fallback, prefer search_index) and then provides a detailed Args section. While slightly long, every section earns its place given the lack of schema descriptions. The organization aids readability and quick scanning.

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 purpose, usage trade-offs, all parameters, and return behavior (compact summaries). The output schema (present per context) handles return value details. No critical gaps are apparent for a list operation; it even explains the relationship to related tools and index syncing 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 has 0% description coverage, but the description's Args section thoroughly documents all six parameters: course_id, limit, offset, sort, filter, and category. It provides defaults, max values, valid filter categories, and specific examples (e.g., sort='new', 'top', 'trending'). This fully compensates for the schema gap.

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

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

The description clearly identifies the tool as a thread-listing fallback, states its scope (freshest N threads, sort options, personal/triage filters), and explicitly distinguishes it from the preferred search_index tool and from get_thread/get_course_thread for reading full content. The verb+resource ('list threads') 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?

Usage guidance is exemplary: it explicitly says to prefer search_index for almost all browsing, lists the exact conditions where list_threads is appropriate (freshness, personal/triage filters), and directs to get_thread/get_course_thread for reading a specific thread. This provides clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses pagination behavior via offset/limit, explains role filtering, and notes the default limit of 50. It does not mention side effects or permissions, but for a list operation these are less critical, and the pagination/filter details add meaningful behavioral context beyond the schema.

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

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

The description is concise and well-structured: a clear opening statement, a usage sentence, and a bullet-like argument list. Every sentence earns its place, with no fluff 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?

The tool is a simple listing operation with 4 parameters and an output schema. The description covers purpose, usage alternatives, parameter semantics, and pagination, making it complete for the tool's complexity. The presence of an output schema means return values need not be described in text.

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 is the sole source of parameter meaning. It explains each parameter: course_id (with how to find it), role (with allowed values and omission semantics), limit (with default), and offset (with paging usage). This fully compensates for the schema's lack of 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 'List enrolled users in a course' with a specific verb and resource. It also distinguishes itself from siblings by explicitly recommending get_enrollment_counts for headcounts and noting when to use this tool (when names or user IDs are needed).

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 when-to-use guidance: 'Use get_enrollment_counts for a quick headcount' vs 'Use this when you need names or user IDs', and even suggests a downstream use case (before calling get_user_activity). It also mentions using list_courses to find course_id, which is a helpful cross-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 provided, the description must carry the full burden of behavioral disclosure. It states the core effect ('prevent new comments') but does not mention reversibility (though unlock_thread sibling implies it), permissions, or side effects on existing comments. This is adequate 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 sentences plus a compact Args block. The main purpose is front-loaded, followed by a brief usage note and parameter explanation. Every word earns its place; 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 single-parameter tool with an output schema, the description covers purpose, usage timing, and parameter origin. It does not explicitly state whether locking is reversible, but the sibling unlock_thread and the non-destructive phrasing ('prevent new comments') provide implicit context. Minor gap for a mutation action.

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

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

Schema description coverage is 0%, so the description must compensate. It does so excellently by explaining thread_id as 'The global thread ID' and providing the source ('from list_threads or search_threads'). This adds significant meaning beyond the bare schema label 'Thread Id'.

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: 'Lock a thread to prevent new comments.' This clearly states the action and its direct effect, distinguishing it from sibling tools like pin_thread or delete_thread. The additional use-case context ('after a question is resolved') reinforces 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 a clear when-to-use context: 'Useful after a question is resolved or a discussion is concluded.' However, it does not explicitly mention alternatives or when not to use it (e.g., 'for a permanent action use delete_thread'), so it falls short of the full 5 criterion but is above average.

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 only states the action 'manually mark' without explaining side effects, such as whether re-marking an existing check-in updates, overwrites, or creates duplicates. It does not mention idempotency, undoability, or required permissions. The enumerated 'kind' values add some clarity but do not compensate for missing behavioral context, which is critical for a mutation 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 concise and well-structured: a one-sentence summary followed by an Args block with bullet points for each parameter. It front-loads the purpose and provides parameter details in a scannable format without any 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?

The description covers purpose and parameters well, and since an output schema exists, return values need not be detailed. However, the behavioral transparency gap (duplicate handling, idempotency, permissions) leaves the description incomplete for a mutation tool with no annotations. The tool has 3 parameters and no annotation support, so more behavioral context would be needed 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 schema has zero parameter descriptions, so the description must compensate. It does this thoroughly: event_id is explained as 'The session ID (from list_attendance_sessions results)', user_ids as 'List of user IDs to check in', and kind with a list of valid statuses ('present', 'late', 'excused', 'absent'). This adds meaning beyond the schema's bare types and defaults.

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: 'Manually mark students' attendance for a session.' It uses a specific verb ('manually mark') and identifies the resource (students' attendance for a session). This distinguishes it from related tools like list_check_ins (viewing) and undo_check_in (reverting), and it references the prerequisite tools (list_users, list_attendance_sessions) to clarify its role.

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 some usage context by directing users to list_users for user IDs and list_attendance_sessions for event_id, which are necessary prerequisites. However, it does not explicitly compare this tool to alternatives such as list_check_ins or undo_check_in, nor does it mention when not to use it (e.g., for automated check-ins). Thus, the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the marking action and its educational purpose, but does not explain side effects (e.g., whether the thread is hidden, locked, or if reversing is needed), permissions, or reversibility. This is a significant gap for a state-changing 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 highly concise: a single purpose sentence, a usage sentence, and a clear Args block. It is front-loaded with the core action and uses 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?

For a two-parameter tool with an output schema, the description covers the essential aspects: what the tool does, when to use it, and the meaning of each parameter. The only missing element is deeper behavioral context (already penalized in transparency), but overall the agent can correctly select and invoke 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 0%, but the description fully compensates by explicitly defining both parameters: thread_id as 'the global ID of the duplicate thread' and original_thread_id as 'the global ID of the original thread it duplicates.' It also tells the agent where to obtain these IDs (list_threads or search_threads), adding actionable meaning.

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+resource: 'Mark a thread as a duplicate of another thread.' It clearly identifies the action and object, and the usage note about pointing students to the original distinguishes it from other thread-modification tools like delete_thread or lock_thread.

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 the tool: 'Use this when a question has already been answered elsewhere to point students to the original.' This gives clear context, though it does not mention when not to use it or name alternative tools (e.g., unmark_duplicate).

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 burden. It discloses the primary behavioral effect (pinning keeps thread at top) but lacks details on permissions, reversibility (unpin), or behavior if already pinned. This is a basic transparency level.

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, front-loaded with the main action and purpose, followed by a use case and argument explanation. 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 tool with one parameter and an output schema, the description covers the core aspects: what, when, and parameter source. It could mention that it's reversible via unpin_thread, but that is not essential given the simplicity and sibling list.

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 explains 'thread_id' as 'The global thread ID' and suggests sources ('from list_threads or search_threads'), adding meaning beyond the schema's type and title. This directly helps the agent correctly supply the 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 clearly states the verb 'Pin' and the resource 'a thread', and explains the effect ('stays at the top of the course feed'). This distinguishes it from sibling tools like delete_thread or lock_thread, which have different purposes.

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

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

The description provides clear context by stating it's 'Good for important announcements or FAQs', implying when to use it. It does not explicitly mention when not to use it or alternatives, but the context is sufficient for most agents.

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 load and explains key behaviors: is_private makes the reply staff-only, is_anonymous hides the author, parent_id nests replies, and content must be in Ed XML format. It doesn't mention permissions or side effects, but the main 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 well-structured: a concise opening sentence, the XML requirement, and a clear bullet-style list of args. Every sentence adds value without unnecessary fluff, and the length is appropriate for the parameter count.

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 (6 params, no annotations) and the presence of an output schema, the description covers all necessary aspects: how to format content, parameter meanings, privacy/anonymity options, and nesting mechanics. It leaves no significant gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, but the description provides detailed meanings for all six parameters, including defaults and restrictions. This fully compensates for the schema's lack of descriptions, adding clear semantic value.

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: 'Reply to a thread with a comment or answer.' It specifies the action (reply), the resource (thread), and optional type (comment/answer), which distinguishes it from sibling tools like create_thread or edit_thread.

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 usage context by explaining where to get thread_id ('from list_threads or search_threads'), and clarifies that 'answer' type only works on question threads. It doesn't explicitly exclude alternatives, but the purpose is clear enough to guide selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses auto-sync behavior (>30 min stale triggers refresh), fallback to stale data on refresh failure, the need to check last_synced timestamp, and that the first call on a large unsynced course may take several seconds. These are meaningful behavioral traits not visible from the schema or sibling 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 long but every sentence earns its place: purpose, sync behavior, query syntax, fallback semantics, latency warning, and usage precedence. It front-loads the core function and then moves from high-level behavior to parameter details. The Args block is clean and consistent with schema names, making it easy to parse.

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

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

Despite the complexity (7 parameters, output schema, sibling tools, no annotations), the description covers all essential context: what it does, how to use it, when to prefer it, sync/latency caveats, and the meaning of every parameter. The output schema exists so return-value details are not required, and the description still mentions 'returns ranked results with full content for top hits' for orientation.

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

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

Schema description coverage is 0%, so the description must fully document parameters. It does: course_id is 'the course ID (use list_courses to find it)', query gets detailed syntax (phrases, prefix, boolean, column-specific), and each filter (limit, category, type, has_staff_reply, is_answered) receives a clear meaning. This adds substantial semantic value beyond the bare 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 opens with 'DEFAULT thread search/browse tool' and clearly states it 'Searches the local BM25-ranked index over all threads in a course.' It explicitly distinguishes itself from siblings by directing use 'before falling back to list_threads/search_threads.' The verb 'searches' plus the resource (threads) and index mechanism make the 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?

Provides explicit guidance: 'Use this for any thread lookup, search, or filtered browse before falling back to list_threads/search_threads.' It also explains when no prior sync is needed ('you do NOT need to call sync_index first in normal use') and how to interpret stale fallback results via the last_synced timestamp. This goes beyond vague context into actionable selection 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 that the tool returns compact summaries, is a fallback, and that full content requires `get_thread`. It does not mention potential rate limits or network behavior, but the key behavioral traits are 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 front-loaded with the most critical guidance (fallback status and preferred alternative), followed by a structured Args list. Every sentence is informative and there is no redundant or filler text.

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

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

For a search tool with moderate complexity, the description covers all necessary aspects: purpose, fallback role, parameter semantics, and follow-up actions. The existence of an output schema means return values need not be detailed, and the description mentions the summary format sufficiently.

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, but the description's Args section compensates fully. Every parameter is explained with meaning, examples (e.g., 'peer review', 'exam'), defaults, and usage tips (e.g., type filter values). This goes well beyond the bare 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 this as a keyword search tool for threads, using the verb 'search' plus specific resource ('threads'). It also differentiates from the sibling tool `search_index` by labeling itself as a 'FALLBACK' option, making its distinct role 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?

Explicit guidance is provided: 'PREFER `search_index`' and 'Only use `search_threads` when the local index is unavailable or sync fails.' This directly tells the agent when to use this tool versus the alternative, and it also suggests following up with `get_thread` for full content.

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 that refreshing is usually automatic, that first sync may take several seconds (full thread download), and that it can clear stale fallbacks. It does not explicitly state whether it is read-only or if it locks anything, but it covers the key behavioral traits.

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?

Every sentence earns its place: definition, when-not-to-use, when-to-use, performance caveat, and parameter guidance. Well-structured with an Args section; 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?

Despite the tool being simple (one param), the description fully covers purpose, usage conditions, performance, and parameter enrichment. The output schema exists, so return values need not be described. It is a complete, self-contained description.

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 explain the parameter. It does: course_id is defined as 'The course ID' and instructs to use list_courses to find it, adding useful context beyond the bare schema. For a single self-named parameter, this is sufficient.

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 ('Force-refresh') and resource ('local search index for a course'), clearly distinguishing it from the auto-syncing behavior of search_index. It directly states the tool's function and 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?

It explicitly says when NOT to call it ('You usually do NOT need to call this'), names the alternative (search_index auto-syncs), and gives concrete scenarios for direct use (external changes, stale-fallback after failure). This is exemplary 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 a key behavioral nuance (both manual and self check-ins), but does not state side effects, permissions, or error behavior. The word 'remove' implies destruction but is not explicit.

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: two sentences plus an explicitly labeled Args section. Every sentence provides value, and it is front-loaded with the main 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 two-parameter tool with an output schema, the description covers the core purpose and parameter semantics well. It lacks optional details like idempotency or behavior for non-existent check-ins, but such details are not essential given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly by explaining both parameters: event_id is the session ID, and user_ids is the list of user IDs whose check-ins to remove. This adds meaning beyond the schema's raw types.

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 'Remove'/'undoes' with a clear resource: check-in records for specific users in a session. It explicitly states this undoes both manual and self check-ins, which differentiates it from related sibling tools like manual_check_in.

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 the usage context: when you need to remove check-ins. It does not explicitly name alternatives or exclusions, but the sibling tool list and the undo semantics make the appropriate use case 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?

No annotations are present, so the description carries the full transparency burden. It states the action but does not disclose whether instructor permissions are required, whether the operation is idempotent (no effect if not endorsed), or any side effects such as reversal via endorse_thread. This is a mutating operation with minimal behavioral detail.

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

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

The description is extremely concise: a single-sentence action followed by a minimal Args section. Every word adds value, with no redundancy or irrelevant details.

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

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

For a simple one-parameter tool, the description covers the purpose and parameter adequately. Since an output schema exists (per context), return value details are not needed. However, it lacks usage context and behavioral caveats (e.g., permissions, idempotency), making it merely minimally viable for an 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 schema only defines thread_id as an integer with no description. The description compensates by explaining it as 'the global thread ID (from list_threads or search_threads)', adding meaningful context about how to obtain and identify the parameter, which goes 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 a specific action ('Remove the instructor endorsement badge from a thread') and the resource (thread), distinguishing it from siblings like endorse_thread and delete_thread.

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

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

The description implies usage by explaining where to get thread_id ('from list_threads or search_threads'), but it does not explicitly state when to use this tool versus alternatives like endorse_thread or delete_thread. No exclusions or alternative recommendations 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?

No annotations are provided. The description states the core behavior (unlock and re-enable comments) but does not disclose whether the operation is idempotent, requires special permissions, or what occurs if the thread is not currently locked. This is minimal yet accurate.

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 very concise and front-loaded with the purpose, followed by a clear Args block. No unnecessary words 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 simple one-parameter mutation, the description covers the action and parameter sourcing. However, with no annotations and no usage alternatives, it leaves gaps around idempotency and permissions. The existence of an output schema means return value details are not required.

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 only defines thread_id as an integer with no description. The description adds meaning by labeling it 'The global thread ID' and directing users to list_threads or search_threads for the value, compensating for the schema's lack of 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 the specific verb 'Unlock' and identifies the resource 'thread', with the clarifying effect 'allow new comments again'. This clearly distinguishes it from lock_thread and other thread-related tools.

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

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

The description provides no guidance on when to use this tool instead of alternatives like lock_thread or delete_thread. It only explains the action and parameter source, not the conditions or scenarios for invocation.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the primary effect (removing the duplicate flag) but omits any side effects, reversibility, permission requirements, or error behavior. For a mutation tool, this 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 concise and well-structured: the main action is front-loaded in the first sentence, followed by a brief, relevant parameter explanation. 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?

Given the tool's simplicity, the description covers the essential purpose and parameter, and an output schema exists. However, it lacks explicit usage exclusions or behavioral caveats, 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 description coverage is 0%, but the description compensates by explaining that thread_id is the global ID sourced from list_threads or search_threads. This adds meaningful context beyond the bare integer type in the schema.

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

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

The description clearly states the action: 'Remove the duplicate mark from a thread, restoring it as a standalone thread.' It uses a specific verb ('remove') and resource ('duplicate mark on a thread'), and distinguishes itself from sibling tools like mark_duplicate (the inverse 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 implies usage by explaining the effect (restoring a thread as standalone) and provides a hint that thread_id comes from list_threads or search_threads. However, it does not explicitly state when to use this tool versus mark_duplicate or exclude any alternative scenarios.

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 clearly states the effect (unpins from course feed) but does not disclose permissions, reversibility, or error conditions. This is adequate for a simple action but lacks depth compared to well-documented mutation tools.

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

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

The description is extremely concise, consisting of a single clear sentence plus a parameter doc line. It is front-loaded and contains no fluff 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 simple unpin operation with one parameter and an output schema present, the description is mostly complete. It covers the action and parameter source, but does not mention any permission requirements or the relationship to pin_thread. Given the tool's simplicity, 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 input schema only shows thread_id as an integer with a title. The description adds valuable context by specifying it is 'the global thread ID' and tells where to obtain it ('from list_threads or search_threads'), which compensates for the 0% schema description 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 clearly states the action: 'Unpin a thread from the top of the course feed.' It uses a specific verb and resource, and the phrase 'from the top of the course feed' distinguishes it from sibling tools like pin_thread, lock_thread, etc.

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

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

The description provides clear context by specifying the action on a thread and telling the user to pass a thread_id from list_threads or search_threads. It does not explicitly contrast with alternatives, but the existence of pin_thread and the verb 'unpin' make the intended usage evident.

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 disclose behavioral traits on its own. It explains boolean semantics for is_closed and is_hidden, but does not mention side effects (e.g., whether closing affects check-ins), permission requirements, or reversibility. The description provides basic operation details but lacks deeper behavioral context.

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

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

The description is well-organized with a clear opening sentence followed by a compact Args list. Each argument gets one line, and the text avoids unnecessary filler. The structure is front-loaded and efficient, though the Args section partially duplicates schema property names.

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 (update operation) and the description covers all parameters and their semantics. The presence of an output schema removes the need to detail return values. It could mention error handling or the impact of closing a session, but the description is adequate for an agent to 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?

The input schema has no per-property descriptions, but the description compensates by explaining event_id as the session ID from list_attendance_sessions, title as a new title with 'omit to keep current,' and the true/false meanings for is_closed and is_hidden. This adds meaningful semantics beyond the bare schema types and defaults.

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 'Update an attendance session' and enumerates the specific operations: close/reopen, hide/unhide, or rename. This clearly distinguishes it from sibling tools like create_attendance_session, delete_attendance_session, and get_attendance_session by focusing on modifying an existing session.

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 'Use this to close/reopen, hide/unhide, or rename a session,' providing direct usage context. It does not mention alternatives or exclusions, but for a straightforward update tool, the intended use cases are 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions returning a URL but does not disclose permissions, file size limits, overwrite behavior, or any other side effects. For a mutation tool, this is a significant 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 sentences plus a one-parameter Args block. The first sentence front-loads the purpose and output, and the Args section adds necessary parameter context. 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 one-parameter upload tool with an output schema, the description adequately covers the purpose, parameter semantics, and the resulting URL. It lacks usage guidance and behavioral caveats, but the tool's simplicity keeps it reasonably complete.

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

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

The input schema only defines file_path as a string with no description. The description's Args section adds 'Absolute path to the file on your computer', which provides essential meaning beyond the schema. This compensates well for the 0% schema description 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 'Upload a file from your computer to Ed Discussion and get a URL' — this gives a specific verb, resource, and output. It also distinguishes itself from sibling upload_file_url by specifying the source as the user's computer.

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

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

There is no explicit guidance on when to use this tool versus alternatives like upload_file_url or download_file. The phrase 'from your computer' implies the local-file use case, but no when-to-use or when-not-to-use conditions are 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, the description carries the full burden of disclosure. It mentions the return value (Ed CDN URL) and the 'without downloading locally' behavior, but it does not disclose potential requirements (e.g., public URL accessibility, size limits) or side effects beyond the upload itself. 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?

The description is two sentences plus a single parameter explanation. Every sentence adds value, and the purpose, return value, and parameter are covered without any 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 simple one-parameter tool with an output schema, the description covers the action, the input, and the return value. It does not address error conditions or limitations, but given the tool's simplicity, the information is largely complete. Minor gaps prevent a perfect score.

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 only the parameter name 'url' with no description. The description adds meaning by explaining it as 'Public URL of the file to upload' and gives examples ('e.g. an image or document URL from the web'), exceeding what the schema alone offers.

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 specific action: 'Upload a file from a URL directly to Ed Discussion without downloading it locally first.' It identifies the resource (Ed Discussion), the verb (upload), and the source (URL), distinguishing it from sibling tools like upload_file (likely local upload).

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 by specifying 'from a URL' and 'without downloading it locally first,' which contrasts with a local upload approach. However, it does not explicitly name alternatives or state exclusions, so it stops short of a full 5.

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