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 is an 'internal client configuration tool', implying access restrictions. It also describes the return content. However, it does not mention authentication needs, error cases, or whether it modifies state (though 'returns' implies read-only).

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

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

The description is two sentences long. The first sentence ('Internal client configuration tool') is slightly redundant with the tool name but adds context about intended audience. The second sentence provides the valuable detail. Overall efficient but could be tightened.

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 no parameters, no output schema, and clear sibling differentiation, the description is complete. It effectively describes the purpose and return content (routing, prompt, rewrite, continuation rules) without leaving gaps.

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 schema description coverage is trivially 100%. The description adds no parameter information, which is acceptable. Baseline for zero parameters is 4, and the description meets that.

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

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

The description clearly states it returns declarative agent routing, prompt, rewrite, and continuation rules. It uses a specific verb ('returns') and identifies the resource (agent runtime config). This differentiates it from sibling tools which are focused on courses, users, and cache.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or contrast with sibling tools like get_cache_status. Given 18 siblings, explicit usage direction is missing.

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 full burden and excels: it explicitly states the tool is read-only ('never calls Moodle'), never returns cached course/category records, and lists exactly what is reported (memory load state, disk cache validity, etc.). No contradictions and full behavioral disclosure.

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

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

Two concise, front-loaded sentences. The first sentence states the action and passive constraint; the second lists the output specifics and behavioral guarantees. No wasted words, every sentence adds value.

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

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

For a simple read-only inspector with one enum parameter and no output schema, the description is fully complete: it specifies purpose, scope, constraints, and reported attributes. No gaps 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 coverage is 100% with a single enum parameter that already has a clear description ('Cache target to inspect: courses, categories, or all'). The description does not add new meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the action ('Inspect') and the resource ('Moodle course and category caches'), and explicitly distinguishes it from mutation tools by adding 'without changing them'. It also lists specific inspection attributes, making the purpose highly specific and distinguishable from siblings like manage_cache.

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 this tool: for inspecting cache state without changes. While it doesn't explicitly say when not to use it or name direct alternatives, the nearby sibling manage_cache implies the alternative for performing cache operations. The lack of explicit when-not guidance prevents a 5.

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

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

With no annotations provided, the description carries the full burden and does so excellently. It explains the tool returns a catalog of callable tools, grouped by source, with a specific table view. This fully describes the tool's behavior—it's a read-only introspection tool with no side effects, which is clearly communicated.

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

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

The description is three sentences with no waste. The first sentence defines the core purpose, the second explains grouping, and the third describes the table view. Every sentence adds distinct value, and it's efficiently front-loaded.

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

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

For a zero-parameter, no-output-schema introspection tool with 17 sibling tools, the description is highly complete. It could optionally mention that the catalog changes dynamically based on configuration, but that's not a significant gap given the simplicity and self-evident nature of the tool.

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

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

The input schema has zero parameters and the description confirms this implicitly by not mentioning any required inputs. The tool is purely getter/self-describing, so there is no parameter documentation needed beyond what the schema provides (100% 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's purpose: it shows the registered tool catalog for the Moodle MCP server. It specifies the output format (grouped by core and plugin tools) and provides a sample table view with columns, making it unmistakably distinct from the sibling tools like list_courses or get_site_info.

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 it returns 'currently callable tools', implying it should be used when an agent needs to discover what tools are available on this MCP server. It doesn't need when-not-to-use guidance because there is no sibling tool with overlapping functionality—this tool is uniquely for introspection of the tool catalog itself.

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 description must fully cover behavior. It states what details are returned (full name, short name, summary, etc.) which is good, but it does not disclose potential side effects, authentication requirements, or rate limits. For a read-only fetch, it is partially 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?

Description is one sentence followed by a list of returned fields. It is concise and front-loaded. Could be slightly more structured (e.g., bullet points) but is clear and to the point.

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

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

For a simple fetch tool with one parameter and no output schema, the description is adequate but lacks some completeness. It lists returned fields but does not explain how to interpret them (e.g., date formats), or error conditions (e.g., invalid courseid). There is no output schema to supplement.

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 covers the single parameter 'courseid' with type and description. The description adds semantic meaning by explaining what the tool returns, which helps the agent understand the purpose. Since schema coverage is 100% and there is only one param, the description provides additional 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?

Description uses specific verb 'Fetch' and resource 'complete details for a single Moodle course', clearly distinguishing from sibling tools like 'list_courses' which retrieves a list, and 'search_courses_by_name' which searches. The tool's purpose 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?

No explicit guidance on when to use this tool versus alternatives (e.g., 'list_courses' or 'search_courses_by_name'). Usage must be inferred from the tool name and description. It's assumed useful for getting detailed info about one course, but no exclusions or context are given.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool requires no parameters and always returns cached data, which hints at non-destructive, read-only behavior. The mention of 'pre-warmed cache' is a useful behavioral detail that helps the agent understand performance and freshness characteristics.

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: the first provides a clear purpose and list of returned data, the second adds operational constraints. This is concise and front-loaded. Minor point: the list of returned items could be slightly trimmed without loss, but it's already 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?

Given zero parameters, no output schema, and no annotations, the description is remarkably complete. It tells the agent exactly what data is returned, how it behaves (cached), and what constraints exist (no parameters). No additional information is needed for an agent to correctly invoke this 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 input schema has zero parameters and the description confirms this with 'No parameters required'. Schema description coverage is 100%, so there are no undocumented parameters. The description adds value by explaining that the absence of parameters is intentional and that the tool always returns cached data, which is beyond what the schema alone conveys.

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

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

The description uses a specific verb ('Returns') and a clear resource ('information about the connected LMS instance'). It lists concrete data returned: site name, version, release, authenticated user, available API functions, and total course count. This clearly distinguishes it from sibling tools like list_courses or get_course which operate on different resources.

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

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

The description explicitly states that no parameters are required and that it always returns cached data. It implies a straightforward use case: calling this tool when you need instance-level metadata. While it doesn't name alternative tools for other contexts, the zero-parameter constraint and specific returned data make the usage context unambiguous.

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

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

No annotations are provided, so the description carries full responsibility. It accurately notes the tool returns a single structured record and returns custom profile fields. However, it does not mention any error conditions (e.g., what happens if the user is not found, or if multiple identifiers are provided) nor read-only behavior—but the description of 'Fetch' implies idempotent read. While it could be more thorough, it is clear and truthful.

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

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

The description is three sentences long: first states the action and search criteria, second gives usage constraint, third describes the return. Every sentence adds necessary information without excess. 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?

Given that there is no output schema, the description compensates by stating that a single structured user record with custom profile fields is returned. The 4 parameters are all documented in the schema with full coverage, so no additional parameter explanation is needed. The description covers essential usage and return shape, making it complete for a straightforward 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no new semantics beyond the parameter schemas but reinforces that exactly one identifier should be used. No additional format or validation hints are needed, so the score holds at baseline.

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

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

The description clearly states the action ('Fetch'), the target resource ('one Moodle user'), and the identification methods ('by exact ID, email, or username'). It distinguishes this tool from sibling tools like 'list_users' or 'search_users' by specifying that it returns a single user based on exact match, not a list or fuzzy search.

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 provide exactly one of the three identifiers (id, email, or username), which guides usage. It does not explicitly compare to alternatives like search_users or list_course_users, but the context of siblings and the tool's purpose imply it is for a direct, exact lookup rather than discovery.

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 is an admin/config tool (implying elevated privileges), describes the return content, and notes the 'no schema' response behavior. Lacks explicit permission requirements, but the context is sufficient for safe tool selection.

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, starting with the tool's purpose and gradually adding detail about what it returns, usage guidelines, and fallback. While slightly longer than necessary, every sentence carries meaningful information and no redundant filler.

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

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

Given zero parameters and no output schema, the description comprehensively covers the tool's functionality: it explains the return value (fields, types, sources, display/filter status), usage constraints, and error handling (no schema leads to a refresh instruction). This is complete for an agent to correctly 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?

The tool has zero parameters, so the schema description coverage is 100%. The description adds no further parameter meaning, which is appropriate. The baseline of 4 applies because with no parameters, the description cannot add value beyond stating 'No parameters required.'

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

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

The description clearly states the tool returns the current user field schema, listing fields, types, sources, and display/filter status. It distinguishes itself from sibling tools like 'refresh_user_field_schema' and 'update_user_field_schema' by specifying its role as a read-only inspector and directing agents to call 'list_users' for ordinary user queries.

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

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

Explicitly states when to use (inspect, configure, show, refresh, troubleshoot schema) and when not to use (before ordinary user listing/filtering, which should use 'list_users'). Also explains the fallback behavior if no schema exists, directing the agent to run 'refresh_user_field_schema'.

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 transparently explains the tool is read-only by listing the returned fields (IDs, names, due dates, etc.) and explicitly states it does not return student submissions, which manages agent expectations well.

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

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

The description is two sentences long with no wasted words. The first sentence states the purpose, and the second sets expectations on what is not returned. Essential for a simple tool.

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

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

Given the tool has only one parameter, no output schema, and a simple purpose, the description adequately covers the key behavioral information. It lacks details like whether ordering or pagination applies, but for a straightforward listing tool, this is sufficient.

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

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

Schema description coverage is 100% with a single required parameter (courseid) already documented as 'Moodle course ID' in the schema. The description adds no further clarification about the parameter beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states it lists assignments in a Moodle course with a specific verb ('list') and resource ('assignments'). It distinguishes from siblings like list_courses by specifying the resource, and from tools that return submissions by explicitly stating what it excludes.

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 this tool (listing assignments in a course) and explicitly states what it does not return ('Does not return student submissions — use a separate tool for that'). It doesn't name specific sibling alternatives, but the exclusion is helpful.

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 a specific set of fields and supports filtering and pagination, which is adequate for a list operation. However, it does not reveal any behavioral traits such as rate limits, permission requirements, or whether results include only active categories by default—leaving some 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—four short, front-loaded sentences—with no unnecessary words. Every sentence adds value: listing return fields, filtering options, use cases, and a cross-tool tip. It is appropriately sized for the tool's complexity.

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 with 100% schema coverage, no output schema, and is a straightforward list operation, the description covers the key information: what data is returned, filtering, pagination, and how to leverage the data with other tools. It is comprehensive enough, though it could mention default limit/offset behavior for total completeness.

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

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

Schema description coverage is 100%, so each parameter already has a clear description in the schema. The tool description adds minimal extra meaning beyond what the schema provides, but it does contextualize filtering by mentioning 'parent ID, exact parent name, and pagination' in a usage-oriented way. This justifies the baseline score of 3.

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

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

The description uses a specific verb ('list') and resource ('LMS categories'), and it clearly distinguishes the tool from siblings by detailing what it returns (e.g., path, depth, course count) and how it can be used for filtering. This differentiates it from tools like 'list_courses' or 'search_courses_by_name'.

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

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

The description explicitly states when to use the tool ('discover available categories, identify active vs inactive categories, and filter courses by category') and provides a practical pointer to use the exact category ID with other tools. However, it does not mention when not to use it or name specific alternatives among the many siblings, so it lacks 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?

No annotations are provided, so the description must convey behavioral traits. It clearly states read-only nature via 'visible to the configured API token' and discloses edge-case behavior (ambiguous category name prompts for ID). It could be improved by explicitly stating whether it mutates data or requires special permissions, but the tone and constraints strongly imply safe, read-only use. No contradictions with annotations (none exist).

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 structured with clear sentences: purpose first, then returned fields, filtering options, limitations, and usage recommendations. It is slightly longer than necessary but every sentence adds value. Minor redundancy (mentioning 'limit and offset' twice) prevents a 5.

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

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

With no output schema, the description compensates by listing returned fields (ID, full name, short name, category, etc.). It covers input parameters, filtering, pagination, and usage context. It lacks details on default behavior (what happens if no filters are applied? Is there a default limit?) and does not mention any rate limits or response size constraints beyond the parameter maximum. For a listing tool with moderate complexity, this is mostly complete but has minor gaps.

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

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

Schema description coverage is 100%—all four parameters are described in the input schema with their types, bounds, and basic purpose. The description adds some value: it explains the use of limit/offset for subset requests, and the categoryname exact-match behavior. However, it does not explain that categoryid and categoryname may be used together or conflict, nor does it clarify whether offset starts from 0 or 1 beyond the schema's minimum 0. Given the high schema coverage, the bar is lower, but the description only adds marginal 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 starts with a specific action ('List all LMS courses'), identifies the scope ('visible to the configured API token'), and lists the returned fields (ID, name, category, etc.). It also distinguishes the tool from siblings by mentioning category-based filtering and pagination, which aligns with sibling tools like 'list_categories' and 'search_courses_by_name'—making it clear that this tool is for broad discovery.

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 guidance on when to use this tool (discovery before drilling into details, preferring exact category IDs from list_categories) and when not to (avoid full course list unless explicitly asked). It also explains category name matching behavior and edge cases (duplicate names force ID usage). This fully covers usage context and alternatives implied by sibling tools.

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

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

No annotations are provided, so the description carries full burden. It discloses return fields (user ID, full name, email, etc.) and deduplication behavior. However, it omits details like default ordering, handling of suspended users, permission requirements, and error behavior, leaving several behavioral aspects unclear.

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 tightly written in four sentences, front-loaded with the primary purpose. Every sentence adds essential information: scope, parameter guidance, return fields, deduplication, and a reminder about category ID sourcing. No redundant or vague phrasing.

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

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

Given the absence of an output schema, the description covers return fields and deduplication. It does not address pagination behavior (limit/offset are parameters but not discussed), error cases, or parameter constraints like partial matching behavior. Still, it provides enough context for typical use.

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

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

Schema description coverage is 100%, providing baseline explanations. The description adds value by specifying the mutual exclusivity constraint (exactly one of the three identifiers) and clarifying that categoryid aggregates across courses. This goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool lists enrolled users in a specific Moodle course or across all courses in a category. It distinguishes from siblings like search_users and list_courses by specifying the scope and mentioning deduplication in category mode.

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

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

Explicitly instructs to provide exactly one of courseid, coursename, or categoryid, and advises using an exact category ID from list_categories. It does not explicitly exclude alternatives like get_user or search_users, but the context is clear enough 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It notes the requirement for an exact userid and the lookup flow, but does not describe what happens on invalid input, error handling, return format, pagination behavior, or authentication needs. The description is partially transparent but lacks key behavioral details.

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

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

The description is concise at five sentences, each serving a clear purpose. It is front-loaded with the main action, then provides prerequisite steps and fallback guidance. No redundancy, and every sentence earns its place.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description focuses on usage flow but does not explain return values, pagination details, or error handling. It is complete for the user's decision context but incomplete for behavioral understanding. The parameter schema covers the parameter descriptions, but the overall tool behavior is not fully 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?

Schema description coverage is 100%, so the baseline is 3. The description repeats the userid requirement already present in the schema but adds no additional meaning or context for the limit or offset parameters. It does not enhance understanding beyond what the structured schema provides.

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

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

The description clearly states the tool lists courses for a specific Moodle user ID, using a specific verb and resource. It distinguishes itself from siblings like list_courses (all courses) and search_users (user lookup) by emphasizing the exact userid requirement.

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 guidance on when to use this tool: when an exact userid is known. It recommends using get_user for exact email/username lookups and search_users for name-based searches, and instructs the agent to ask the operator to choose if multiple matches occur. This is thorough and actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool modifies caches (refresh/clear) and mentions memory implications, but omits important details like required permissions, synchronous vs asynchronous operation, or potential performance impact on other users. The description is adequate but not thorough.

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

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

The description is three sentences long and front-loaded: the first sentence states the core purpose. The second adds behavioral context. The third repeats parameter info already in the schema, which could be more concise. Overall, it is efficient but not maximally tight.

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

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

For a tool with two simple parameters, no output schema, and no nested objects, the description covers the basic functionality. However, it lacks context about side effects, error behavior, required capabilities, and the relationship to sibling tools like get_cache_status. The absence of an output schema is not a problem, but the description should at least hint at what the tool returns (e.g., success indication).

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

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

Schema coverage is 100% with both parameters already described in the input schema. The description adds minimal value by repeating the enum values and slightly rephrasing the same information (e.g., 'all to affect both courses and categories'). No new semantic context beyond the schema is provided.

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 manages Moodle course and category caches, with specific actions (refresh/clear) and targets (courses/categories/all). This verb+resource combination is unambiguous and distinguishes it from sibling tools like get_cache_status (read-only) or list_courses (data retrieval).

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., get_cache_status). It only explains how to use the parameters, not the context or prerequisites. No explicit when-to-use or when-not-to-use advice is given.

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

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

No annotations are provided, so the description carries the full burden. It explains that the tool samples fields from the current user and enrolled users across courses, that it creates or updates the schema, and that operator overrides on still-existing fields are preserved when force is true. It does not mention return value or potential side effects (e.g., whether it modifies the Moodle instance), but the behavioral details given are sufficient for a refresh operation.

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

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

The description is concise and well-structured. It leads with the core purpose in the first sentence, then provides additional context, followed by usage guidelines and parameter explanation. Every sentence adds value, and there is no redundancy or fluff. The front-loading of the key action helps the agent quickly understand the tool's 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?

Given the tool has one optional parameter, no output schema, and no annotations, the description is reasonably complete. It covers the action, the scope of data sampled, usage scenarios, and parameter behavior. Minor gaps include not mentioning the output format (e.g., whether it returns a summary or confirmation) and not explicitly stating that this is a write operation. However, the overall coverage is strong for a tool of this 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 100%, so the baseline is 3. The description adds significant value beyond the schema: it explains the default value (false), the difference between true and false ('re-merges all fields from scratch' vs. 'only updates if there are differences'), and the preservation of operator overrides. This provides the agent with clear decision-making context for 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 tool's purpose: 'Discover all available user fields from the connected Moodle instance and create or update the user field schema.' It uses specific verbs ('discover', 'create or update') and a specific resource ('user field schema'), and it distinguishes itself from sibling tools like get_user_field_schema (read-only) and update_user_field_schema (manual update) by focusing on automated discovery from the source.

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 lists three clear use cases: 'when connecting to a new Moodle instance for the first time, or after a Moodle admin adds/removes custom profile fields, or when the operator asks to refresh the user fields.' It also explains the behavior of the force parameter. However, it does not explicitly state when to use alternative tools (e.g., get_user_field_schema for reading) or when not to use this tool, though the context of sibling tools makes this somewhat implicit.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. The description reveals no side effects, authentication requirements, rate limits, or failure modes (e.g., what happens if a field key doesn't exist). It is a straightforward reorder operation without additional behavioral context, warranting a moderate score.

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

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

The description is a single paragraph with front-loaded purpose ('Reorder displayed user table columns... Use this when...'). The examples are concise and illustrative, adding practical guidance without redundancy. Every sentence serves a clear 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?

Given the moderate complexity (4 params, no output schema), the description covers the main use case well: reordering via relative or absolute positions. It lacks explanation of what happens on success or error, and does not address parameter exclusivity. However, it is close to complete for a focused reorder 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 100%, so the baseline is 3. The description adds value by giving natural language examples mapping to parameter combinations (e.g., 'move department after email' → after parameter), but it does not explain the semantics of required vs. not-allowed parameter combinations (e.g., that after, before, and position are mutually exclusive). The examples illustrate usage but leave restrictions implicit.

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: 'Reorder displayed user table columns in the user field schema.' The verb 'reorder' is specific to the resource 'displayed user table columns'. Among siblings like get_user_field_schema, refresh_user_field_schema, and update_user_field_schema, this description uniquely distinguishes the reordering action.

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

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

The description explicitly says 'Use this when the operator asks to move a column left, right, first, last, before another field, or after another field.' It also instructs the agent that field and target values must be exact field keys from get_user_field_schema, listing examples. This tells the agent when to invoke this tool and what inputs to use, effectively differentiating it from siblings like update_user_field_schema.

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

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

The description mentions case-insensitive search and partial matching, which are helpful behavioral traits. However, with no annotations provided, the description carries more burden; it does not disclose potential performance concerns for large datasets, rate limits, or whether it returns archived courses. The lack of annotations raises the bar, and the description does not fully compensate.

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 at three sentences, clearly front-loading the purpose and usage context. Each sentence adds value: purpose, when-to-use, and behavioral details (partial matching, case-insensitivity). It could be slightly more compact by removing redundancy (e.g., 'case-insensitive partial match' appears in both description and schema), but overall 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?

Given the tool is a simple search with two parameters, no output schema, and no annotations, the description adequately covers the key aspects: search behavior, match strategy, return fields, and how to use the results. It doesn't explain pagination or default limit, but those are covered by the schema description for the 'limit' parameter. Minor gaps exist (e.g., what happens when no results), but overall complete for this complexity level.

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

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

Schema description coverage is 100%, so the schema already documents the two parameters (searchTerm and limit) with descriptions. The description adds some context by mentioning specific fields matched (course full name, short name, ID number) and what is returned (course ID, full name, short name, category, visibility), but this is already implied by the tool's purpose. The baseline of 3 is appropriate as the schema does the heavy lifting.

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 specific verbs ('Search for courses by name') and clearly states the resource (courses) and the matching scope (name, with partial matching on various fields). It distinguishes from siblings like 'list_courses' by emphasizing that this is for finding course IDs when only a partial name is known.

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

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

The description explicitly states when to use this tool: 'finding course IDs when you only know part of the course name.' It also provides a concrete use case: 'Use this to find course IDs for other tools like list_course_users.' This makes it clear how it fits into workflows and differentiates it from listing all courses.

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?

Given no annotations exist, the description must fully disclose behavioral traits. It clarifies that filtering is server-side via Moodle, not preloaded client-side, which is important for understanding performance and accuracy. It also explains the offset pagination (in the offset parameter description). However, it doesn't state what happens on error (e.g., invalid search field, empty result), or whether the tool is read-only/idempotent (implicitly yes, but not stated). Still, with no annotations, this is strong transparency.

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

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

Three sentences, each packed with value: the first states purpose and searchable fields; the second provides usage context and behavioral fact; the third gives a critical usage guideline about filtering and handling multiple matches. No wasted words. Front-loaded with the essential 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?

Given the tool has 7 parameters, no output schema, and no sibling tool that does exactly the same (only get_user for specific ID), the description covers usage, behavior, and the key parameter nuance (offset). It does not explain return format or what happens when multiple fields are provided (priority or conjunction), which could be needed for complete understanding. But for a search tool, it is largely sufficient. A 5 would require documenting the return structure or combining logic.

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

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

Schema coverage is 100%, so baseline is 3. The description does not repeat parameter schemas but adds value by explaining the offset behavior ('applied after Moodle returns matches') which clarifies pagination semantics that the schema alone does not. It also stresses the requirement to provide 'at least one standard Moodle search field', implying that the tool may fail or return no results if used without any filter, which is not obvious from the optional schema. One could argue for a 5, but the score stays at 4 because the added value is not exhaustive (e.g., no guidance on combining multiple fields).

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 'Search' and the resource 'Moodle users', and lists the specific search fields (firstname, lastname, email, username, idnumber). This distinctively differentiates it from siblings like list_courses, get_user (which may require a user ID), or list_course_users (which filters by course). The scope is 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 explicitly says 'Use this for direct person lookup, not structured directory filtering or reports.' It provides a prerequisite ('Provide at least one standard Moodle search field'), explains behavior ('Moodle performs the filtering first; this tool does not preload the full user directory'), and names an alternative ('If a directory listing plugin is installed, prefer that plugin for filter-style requests'). It also warns against premature downstream actions when multiple matches occur. 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?

No annotations exist, so the description carries the full burden. It discloses that only included fields change, omitted fields keep current settings, and it's an admin/configuration tool. Could mention permissions or reversibility, but the current disclosure is strong.

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

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

Well-structured with purpose first, then usage conditions, field keys, and examples. Slightly verbose but every sentence adds value. The examples are particularly helpful.

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 no output schema, the description need not explain return values. It covers input parameters thoroughly, usage context, field keys, examples, and references sibling tools. All necessary information is present.

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

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

Schema description coverage is 100%, but the description adds significant value: explains the shortcut vs. updates parameter, lists common field keys, and provides multiple examples. This goes well beyond the schema's brief 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 'Update display and filter settings for specific user fields' with a specific verb and resource. It distinguishes from siblings like get_user_field_schema (read) and refresh/reorder variants by indicating it's a configuration update tool.

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

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

Explicitly states when to use: 'when the operator wants to show or hide a field... enable/disable for filtering.' Also clarifies when not to use: 'not a prerequisite for ordinary filtered user-list requests.' Provides field key guidance and examples.

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