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

With no annotations provided, the description carries full burden. It discloses idempotency (a key behavioral trait) and the optional nature of 'recursos_ids'. However, it misses critical details like required permissions, whether changes are reversible, or potential side effects on student access, which are important for a visibility-changing tool.

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

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

The description is extremely concise—one sentence plus a note on idempotency—with zero wasted words. It front-loads the core action ('Make visible') and efficiently covers key aspects. Every element earns its place, making it highly readable and focused.

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 annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks details on permissions, error conditions, return values, or how visibility changes affect students. For a tool that modifies student access, this leaves significant gaps in understanding its full impact and usage context.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'seccion_id' and 'recursos_ids' (modules subset) but provides no semantic context—e.g., what a 'seccion_id' represents or how 'recursos_ids' relate to modules. This adds minimal value beyond the bare schema, failing to adequately address the coverage gap.

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

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

The description clearly states the verb ('Make visible') and resource ('previewed section'), specifying the action of revealing content to students. It distinguishes from siblings like 'publicar_preview' by focusing on confirming visibility rather than initial publishing. However, it doesn't explicitly differentiate from all siblings, keeping it at 4 instead of 5.

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

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

The description implies usage when a section is previewed and needs to be made visible, with optional module selection via 'recursos_ids'. It mentions idempotency, suggesting safe repeated use. However, it lacks explicit when-not-to-use guidance or clear alternatives among siblings like 'publicar_ficha_clase', leaving room for ambiguity.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool as a read-only operation ('returns') and specifies the scope of data returned, which is helpful. However, it doesn't mention potential limitations like permissions needed, error conditions, or rate limits, leaving some behavioral aspects unclear for a tool with no 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?

The description is front-loaded with the core purpose in the first sentence and follows with a clear usage guideline. Every sentence adds value without redundancy, making it efficiently structured and 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's moderate complexity (2 parameters, no output schema, no annotations), the description provides good context on purpose and usage. It explains what the tool returns and when to use it, which is sufficient for a read-only tool. However, without an output schema or annotations, it could benefit from more details on return format or error handling, slightly limiting 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?

With 0% schema description coverage, the description must compensate for undocumented parameters. It explains the purpose of the tool's output but doesn't directly describe the parameters. However, the context ('compact radiograph of a Moodle course') and the parameter names ('course_id', 'incluir_ultimas_clases') are intuitive, and the description implies the tool fetches course-specific data, adding some semantic value. Since there are only 2 parameters, this partial compensation earns a 4.

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 with specific verbs ('returns a compact radiograph') and resources ('Moodle course'), detailing exactly what information is provided (metadata, sections with module counts, recent MCP-published lessons, enrolment counts). It distinguishes this tool from siblings by explaining its preparatory role for publishing a Ficha, making it highly specific and differentiated.

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 ('Call this before publishing a Ficha so the agent knows where it fits'), providing clear context and purpose. It distinguishes it from sibling tools by positioning it as a preparatory step for publishing operations, offering specific guidance on its role in the workflow.

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 adds valuable behavioral context: it discloses idempotency ('republishing the same Ficha updates in place, never duplicates'), default behavior ('Default modo is `oculto`'), and workflow relationships. It doesn't mention error conditions or permissions, 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?

Three sentences, each essential: first states purpose, second covers idempotency and default, third provides workflow guidance. No wasted words, front-loaded with core functionality.

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 4-parameter mutation tool with no annotations or output schema, the description is strong but not fully complete: it explains key behaviors (idempotency, defaults, workflow) but lacks details on error handling, response format, or side effects. Given the complexity, it's above minimum viable but could be more comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'modo' parameter's default value and meaning ('oculto' means hidden), and implies 'ficha_path' refers to a markdown file. It doesn't detail 'course_id' or 'section_id' semantics, but the tool name and context provide some inference.

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

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

The description clearly states the verb ('Publish') and resource ('a FichaClase markdown file as a Moodle section with component modules'), distinguishing it from siblings like 'publicar_preview' (preview workflow) and 'confirmar_preview' (confirmation step). It specifies the exact transformation from input to output.

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

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

It explicitly provides when-to-use guidance: 'Use `publicar_preview` + `confirmar_preview` for the preview workflow' distinguishes this as the final publishing tool versus preview alternatives. It also mentions the default mode ('oculto') as a usage hint.

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 effectively describes key behaviors: it's a mutation tool (implied by 'Publish'), returns a specific shape (similar to 'publicar_ficha_clase' plus a 'preview_url'), and has side effects (creating a hidden preview accessible only to teachers). However, it lacks details on permissions, error handling, or rate limits, which are important for a mutation tool without annotations.

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

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

The description is highly concise and well-structured in two sentences. The first sentence states the core action and return value, while the second clarifies the preview state and next steps. Every word earns its place, with no redundancy or fluff, making it easy to parse and understand quickly.

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

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

Given the tool's complexity (a mutation with preview functionality), no annotations, no output schema, and low schema coverage, the description does a good job covering the core behavior and workflow. It explains the preview mode, return shape, and relationship to 'confirmar_preview'. However, it misses details like error cases or the exact return structure, which could be important for agent invocation without an output schema.

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

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

The input schema has 2 parameters with 0% description coverage, so the schema provides no semantic information. The description does not explain what 'ficha_path' or 'course_id' represent, their formats, or constraints beyond the schema's basic types. It adds no parameter-specific meaning, but since there are only 2 parameters, the baseline is slightly higher than minimal, though it fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the specific action ('Publish a FichaClase in hidden preview mode') and resource ('FichaClase'), distinguishing it from sibling tools like 'publicar_ficha_clase' (which likely publishes publicly) and 'confirmar_preview' (which confirms the preview). It explicitly mentions the preview mode and the target audience (teacher vs. students), making the purpose distinct and well-defined.

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: for publishing in 'hidden preview mode' that teachers can review, and it specifies an alternative ('confirmar_preview') for making it visible to students. It also implies when not to use it (e.g., for direct student access or final publication without preview), offering clear context for tool selection.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the return shape: 'Returns `{ data }` on success, structured `meta.code` + `isError: true` on failure,' giving agents a concrete expectation of both success and error behavior. The 'escape hatch' metaphor additionally signals that this tool bypasses typical facades, though it does not detail potential side effects or validation behavior.

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

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

The description is composed of two tightly crafted sentences. The first front-loads the core purpose, and the second packs in return format and usage guidance. There is no filler or repetition of schema details.

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

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

For a generic escape-hatch tool, the description covers the essentials: what it does, when to prefer alternatives, and the shape of success/failure responses. It could also warn that function calls are not validated and may have destructive effects, but the 'escape hatch' label and the nudge toward high-level facades partially cover that.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter meaning. It only says 'with arbitrary parameters,' which essentially repeats the free-form nature of the `params` object already visible in the schema. It does not explicitly state that `params` are passed directly to the Moodle function or how they map to function arguments, leaving a significant gap for a tool that is inherently parameter-driven.

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

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

The description opens with 'Escape hatch: call any Moodle Web Services function with arbitrary parameters,' which clearly and specifically identifies the tool's purpose and scope. This distinguishes it from high-level sibling tools that each target a single Moodle operation, positioning ws_raw as a generic passthrough.

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 closing sentence, 'Prefer high-level facades when they cover your use case,' gives explicit guidance on when to use this tool versus the alternatives. It also labels the tool an 'escape hatch,' which implies it should be a fallback option, not the first choice.

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