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?

With no annotations, the description carries the full burden; 'Fetch' and 'Returns' strongly imply a read-only operation, and the enumerated return fields give useful output context. However, it does not disclose error behavior for a missing course, permission requirements, or that the result is a single object.

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 tight sentences with the action and scope front-loaded and the returned fields listed compactly. Minor filler in 'structured details' but no wasted sentences.

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 lookup with no output schema, the description compensates by enumerating the returned fields. Only the missing error/not-found behavior keeps it short of complete.

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

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

Schema description coverage is 100% for the single courseid parameter, so the schema already documents it fully. 'By ID' restates the parameter's role without adding format, range, or sourcing guidance 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?

Specific verb ('Fetch') plus resource ('structured details for a single Moodle course') plus the selecting key ('by ID'). It is clearly distinguishable from siblings like list_courses and search_courses_by_name, which return collections.

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 is implied by the singular scope and ID-based lookup, but the description never states when to prefer this over search_courses_by_name or list_courses, nor what happens if the ID is unknown. No exclusions or prerequisites 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?

With no annotations, the description carries the full burden. It discloses the return shape ('single structured user record including any custom profile fields'), which partially compensates for the missing output schema, but says nothing about permission requirements, behavior when no user matches, or whether the call is 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?

Two sentences, front-loaded with the action and lookup keys, followed by the return shape. No filler and every clause carries 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 single-record lookup with a fully described schema and no annotations, the description covers purpose, key selection, and return shape. It lacks error/permission behavior, but nothing critical to making the call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema does not express: no parameter is marked required, yet the description mandates exactly one of id/email/username. That is genuine semantic value 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?

States a specific verb (Fetch) and resource (one Moodle user) and names the three lookup keys, with 'exact' implicitly contrasting with the fuzzy search_users sibling. It stops short of naming search_users outright, so an agent must infer the boundary rather than being told.

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?

'Provide exactly one of id, email, or username' is a cardinality constraint rather than usage guidance, and the presentation hint is duplicated from the schema. There is no explicit guidance on when to use this over search_users or list_course_users, so the selection context is only implied.

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 exist, so the description carries the burden: it discloses the return fields, the exact-match requirement for categoryname, and the disambiguation behavior (asks for ID rather than guessing) — genuinely useful behavior beyond structured fields. It omits auth/permission specifics (beyond 'configured API token') and any rate-limit or max-page guidance, keeping it short of 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?

Front-loaded with purpose and return shape, then filters, then usage guidance. Mostly every sentence earns its place, though limit/offset are explained twice (in the filter list and the 'first 10/first 50' sentence), a minor 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?

With no output schema, the description supplies the return fields; with no annotations, it supplies usage and disambiguation rules. For a read-only list tool with 5 optional params, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: categoryname must match exactly and how ambiguity is resolved, the meaning of visible=true/false, and concrete limit/offset examples ('first 10 or first 50'). It does not restate the 1500 max.

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

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

States a specific verb+resource ('List LMS courses') scoped to the configured API token, and enumerates the returned fields. The mention of list_categories and get_course lets an agent place it among siblings without opening schemas.

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

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

Explicit when-to-use ('discover available courses before drilling into details'), when-not ('Do not request the full course list unless the user explicitly asks for all courses'), and an alternative ('Prefer exact category IDs from list_categories'). Filtering intent for visible and limit/offset is spelled out.

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 and does well: it enumerates the returned fields (ID, name, email, department, institution, last access, roles) and discloses non-obvious semantics such as category-mode deduplication of overlapping users. It omits pagination/result-cap behavior and any auth or rate-limit notes, so it is not fully complete.

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

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

Four sentences, each earning its place: purpose, required-argument rule, return payload, and category-mode nuance. The most decision-relevant information (scope and the one-of constraint) 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?

With no output schema and no annotations, the description compensates by listing return fields and deduplication behavior, which is exactly what an agent needs. Minor gap: no guidance on limit/offset pagination or behavior when the 500-user cap is hit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a mutual-exclusivity constraint ('exactly one of courseid, coursename, or categoryid') that the schema does not express via anyOf/oneOf, plus clarification that coursename is partial-match and categoryid aggregates. That is real added 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?

States a specific verb+resource ('List enrolled users') with two explicit scopes (single course vs. whole category), which cleanly separates it from siblings like search_users and list_user_courses. An agent knows exactly what entity set is returned without opening the schema.

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

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

Gives a concrete selection rule ('Provide exactly one of courseid, coursename, or categoryid') and routes the agent to list_categories for valid category IDs. It stops short of naming explicit alternatives to use instead (e.g. search_users for ad-hoc user lookup), so it is clear context without full when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the critical precondition (exact userid) and the disambiguation workflow, which is valuable. However, it does not mention pagination behavior (despite limit/offset params) or what happens with an invalid userid, leaving some behavioral gaps for a tool with zero annotation coverage.

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?

Four tight sentences, front-loaded with the core action, then prerequisites and disambiguation steps in a logical order. Every sentence earns its place with no 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 precondition and disambiguation guidance make the definition usable without opening sibling schemas, which is strong for a lookup tool. It stops short of describing pagination or error behavior for an invalid userid, but for this tool's complexity and with a fully documented schema, it 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?

Schema description coverage is 100%, so the schema already documents userid, limit, offset, and _silo with descriptions and constraints. The description reinforces that userid must be exact, which adds marginal value, but does not explain pagination semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource (list courses) with a precise scope (a specific Moodle user ID) and distinguishes itself from siblings list_courses and list_course_users. The requirement of an exact userid is stated immediately.

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 routes to get_user for email/username lookups and to search_users for name-based lookups, and instructs the agent to ask the operator to choose a userid when multiple matches exist. This is a model example of when-to-use and what-to-do-when-ambiguous 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 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?

With no annotations, the description carries the behavioral burden and does well: it discloses that Moodle performs filtering server-side and that the tool does not preload the full directory, plus a mutation-adjacent caution about not guessing downstream actions. It does not cover auth/permission requirements or rate limits, which keeps it short of 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?

Front-loaded with the core verb+resource, then layered with alternatives and cautions in a logical order. It is slightly long with several conditional sentences, but each adds a distinct constraint rather than repeating itself.

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?

An 8-parameter tool with a nested internal _silo object and no output schema, so the description needs to explain behavior; it covers filtering, no-preload, and ambiguous-match handling. It leaves the internal _silo filter unexplained (though the schema marks it INTERNAL) and says nothing about return shape or pagination interaction.

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 enumerated parameters and their meanings are already fully documented in the schema; the description names the standard search fields but adds no syntax, matching semantics, or format detail beyond that. 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?

States a specific verb (search) and resource (Moodle users) plus the exact searchable fields (firstname, lastname, email, username, idnumber), and explicitly distinguishes itself from 'structured directory filtering or reports', routing the agent away from sibling tools like list_course_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?

Gives explicit when-to-use (direct person lookup), when-not (filter-style requests, for which it names a directory listing plugin as the preferred alternative), a precondition (provide at least one standard search field), and a downstream rule (select the correct user ID rather than guessing). Nothing is left to inference.

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

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

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.