DesarrolloMCP

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

Annotations already declare readOnly, idempotent and closed-world behavior, so safety is covered. The description goes further by disclosing the return shape (título, resumen, tipo, id/slug, URL), the relevance ordering, and the empty-result behavior, which is real added context; it stops short of explaining scoring or how 'relevance' is computed.

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 purpose, then usage and fallbacks; every sentence carries actionable information. It is slightly long with the branching follow-up/fallback instructions, but none are 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?

With no output schema, the description compensates by describing the return fields and ordering, and it fully covers when to invoke, what to do with results, and what to do when nothing is found. Nothing an agent needs to call it 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 description coverage is 100%, so the schema already documents consulta, tipo (with enum) and limite. The description adds no extra semantics about the parameters, so the baseline 3 applies.

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

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

States a specific verb (buscar) and precise resources (lecciones del curso, artículos del blog), and clearly distinguishes itself from the read/list siblings by being the keyword-search entry point. An agent can tell what it does 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?

Explicitly says to use it first when the user asks about a topic and the right page is unknown, names the follow-up tools (leer_articulo, ver_leccion/leer_leccion), and even prescribes fallbacks (synonyms/English, or ver_temario + listar_articulos) when results are empty. When-to-use, alternatives and failure handling are all covered.

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?

Annotations already declare readOnly/idempotent/closed-world, and the description adds value beyond them: it discloses that no account is required and describes the exact return shape (Markdown body plus title, date, URL, related lessons), which matters since there is no output schema.

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

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

Four tight sentences: return contents first, then the usage trigger, the fallback, and the citation requirement. No filler, and the most decision-relevant information (what you get, when to call) 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?

For a one-parameter read tool with no output schema, the description covers inputs (slug provenance), outputs (article fields and lessons), auth ('no necesita cuenta'), and error recovery. Nothing needed to call it 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% and the single slug parameter is already fully documented there, including the max length, the 'without /blog/' constraint, an example, and the fact it is returned by buscar/listar_articulos. The description only repeats the provenance, so it adds little 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 states a specific verb+resource (retrieve the full Markdown text of a blog article) and enumerates the payload (title, date, URL, related course lessons). It also distinguishes itself from siblings by noting the required slug comes from buscar or listar_articulos.

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

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

It gives an explicit trigger ('cuando ya tienes el slug ... y necesitas el contenido para responder o resumir'), a fallback for the failure case ('Si el slug no existe, búscalo con buscar'), and an instruction to cite the article URL. Alternatives and conditions are fully 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the access model (lesson 01 and Básico with an account; Avanzado/Experto only if purchased), the login requirement, the fallback behavior when access is denied (returns the public ficha and how to obtain it), and a concrete rate limit (60 lessons/day per student on MCP, unlimited on the web). This is exactly the kind of context annotations cannot carry.

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 purpose, then access, then usage, then limits, with no filler sentences. It is dense and information-rich; slightly long for a single-parameter read tool, which keeps it just short of 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?

No output schema exists and there is one documented parameter, yet the description fully covers what the agent needs: what is returned, the access prerequisites, the denial fallback, and the rate ceiling. Nothing material 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 description coverage is 100% and there is a single well-documented `slug` parameter, so the schema already does the heavy lifting. The description adds only an indirect pointer ('ver_temario los lista') to where slugs come from, which is marginal added value. 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 and resource: returns the FULL text of a course lesson in Markdown. It distinguishes itself from the similarly named sibling ver_leccion (public preview) by scoping the full-text/access-gated behavior, so an agent can pick the right tool without opening either 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?

Explicitly tells when to use it ('para estudiar o explicar una lección concreta con su texto') and names the alternative for the no-account case ('para saber de qué trata sin cuenta basta ver_leccion'). The routing condition is unambiguous.

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

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

Annotations already establish readOnly, idempotent, closed-world reads. The description adds value beyond them by specifying sort order, the fields returned, and the hay_mas pagination contract with the exact follow-up call. It stops short of anything about failure modes or rate limits, but the annotation coverage makes this 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?

Dense but front-loaded: the scope and ordering come first, then filtering, routing, and pagination. Every sentence carries an operational instruction, though the final pagination sentence is somewhat procedural for the primary description body.

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 correctly enumerates the returned fields and the pagination signal (hay_mas), and provides the follow-up action. Nothing an agent needs to invoke it 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 baseline is 3. The description goes further by explaining the pagination contract in prose ('desde igual a la posición siguiente'), tying desde and limite together in a way the isolated schema descriptions do not.

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

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

States a specific verb (listar) and resource (artículos del blog), adds ordering (más reciente al más antiguo) and the surfaced fields (slug, fecha, tema, resumen, URL). It clearly distinguishes itself from buscar and leer_articulo, so an agent can route without opening a 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?

Explicit routing: use it for novedades or all content on a tema, and 'si buscas algo concreto, usa buscar'. It also names the downstream step (leer_articulo) and the pagination loop condition (hay_mas true → repeat with desde), covering when and how to use it.

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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the login requirement and the conditional return behavior (an upgrade path only appears when the student lacks the top level).

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

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

Purpose is front-loaded and the alternative-routing comes after, which is the right order. The returned-field enumeration is slightly dense but each item carries meaning for an agent deciding whether to call it.

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?

There is no output schema, so the field-level description of what is returned is load-bearing and is present. Combined with the auth prerequisite, use case and sibling routing, the definition contains 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?

With zero parameters the schema documents nothing to add, and the description usefully confirms this ('No tiene parámetros'), removing any ambiguity about how to invoke it. Baseline 4 applies for a parameterless tool.

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?

Names a specific resource (the logged-in student's account) and enumerates exactly what it returns: email, access level, accessible levels, sign-up date, and upgrade path. It explicitly distinguishes itself from siblings by naming mi_progreso and ver_planes, so the agent can route without opening any 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 an explicit use case ('Úsala para saber qué puede leer la persona antes de recomendarle lecciones o un plan') plus the alternatives and the condition selecting them ('para lo que lleva hecho, usa mi_progreso, y para los precios, ver_planes'). It also states the prerequisite ('Necesita iniciar sesión').

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?

Annotations already declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description adds a genuinely new behavioral fact not present in structured data: it requires an authenticated session ("Necesita iniciar sesión"). It stops short of describing pagination or failure behavior, but for a small read-only tool this is solid.

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

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

Front-loaded: the return contents come first, then the auth requirement, then the usage rule and follow-up. Information-dense and free of filler, though the opening sentence packs a long list of fields that could be slightly tighter.

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 carries the return-value burden and does so by naming the exact fields returned, plus the auth requirement and the routing to leer_leccion. Nothing an agent needs to invoke it 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?

Zero parameters, so the baseline is 4. The description confirms this explicitly ("No tiene parámetros"), which is consistent with the empty schema and leaves nothing ambiguous for the caller.

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 (student's progress in the course) and enumerates exactly what is returned: completed lessons by level, percentage, last five finished, and the next one with its URL. This clearly separates it from siblings like leer_leccion, ver_leccion, and mi_cuenta without opening any 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 an explicit trigger ("when the person asks where they are or what to study now") and names the follow-up tool and action (open the next lesson with leer_leccion). The agent knows both when to call this and what to do next.

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?

Annotations already cover readOnly/idempotent/openWorld, but the description adds real value: it discloses that the lesson body is NOT returned, that no account is needed, and that leer_leccion requires login plus level access. A minor gap remains on the exact shape of "cómo se accede", but the behavioral context is strong and consistent with 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?

Front-loaded with purpose, then scope exclusion, then alternatives and error handling — logical and dense. It is three information-heavy sentences rather than padding, though slightly packed; every clause carries weight.

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 the returned fields, and it covers auth requirements, the alternative tool, and error recovery. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%; the schema alone documents the slug format, length limit and level-prefix examples. The description adds only a slight hint via the error case ("Si el slug no existe"), so the baseline of 3 applies since 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?

States a specific verb+resource ("Ficha pública de una lección") and enumerates exactly what it returns (resumen, objetivos, secciones, tiempo de lectura, cómo se accede, URL). It explicitly clarifies the negative scope ("No devuelve el cuerpo de la lección") and distinguishes itself from the sibling leer_leccion.

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 it ("para explicar qué enseña una lección sin necesidad de cuenta"), names the alternative for full content (leer_leccion, with its auth/level requirements), and gives fallback routing ("Si el slug no existe, llama a ver_temario"). 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds genuinely new behavior context: the one-time-payment model (no subscription), the 14-day refund policy, and the constraint that no purchase action can be taken here.

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

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

Content is front-loaded: what is returned first, then when to use it, then the alternative, then the constraint. Only the final sentence ('No tiene parámetros') fails to earn its place, since the empty input schema already conveys this.

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 fully enumerates what the agent will receive (tiers, prices, inclusions, guarantee, URL), and with no parameters there is nothing else an agent needs before calling it. Nothing material is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a non-parameterized tool is 4. The closing note that it takes no parameters is harmless but redundant with the empty schema.

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

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

Specifies the exact resource returned (course tiers) and its scope: price in euros, one-time payment model, what each tier includes, refund guarantee, and the plans-page URL. It clearly separates this tool from siblings by naming mi_cuenta as the source for what the user already owns.

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 trigger conditions ('when the person asks about prices, which tier to buy, or what each includes'), an explicit alternative (mi_cuenta for current entitlements), and a clear boundary that purchases happen on the web and cannot be completed through this tool.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: no filter returns all 26 lessons, and it discloses the composition of the result (slug, título, descripción, nivel, forma de acceso, precio, resumen por nivel). It stops short of describing pagination or ordering, which is a minor gap for a fixed-size catalog.

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 action and scope, then usage and routing in a compact sequence of clauses. The enumeration of returned fields is dense but earns its place by compensating for the absent output schema; the whole definition remains a single tight paragraph with no filler.

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

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

For a parameterless-filter, read-only list tool with no output schema, the description supplies everything an agent needs: scope, the shape of the returned records, the default behavior without filters, and the handoff to sibling tools. Nothing material is left to inference.

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

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

Schema coverage is 100% and the single enum parameter with its three values is fully documented in the schema, including the default behavior of returning all 26 lessons. The description corroborates the enum options but adds no format, syntax or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lista las lecciones del curso de MCP') and quantifies scope (26 lessons across three levels) plus the returned fields. It explicitly names the sibling tools it is not (buscar for a single topic, ver_leccion for a public sheet, leer_leccion for full text), so an agent can route without opening any 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 explicit when-to-use cases ('enseñar el plan de estudios completo o para obtener el slug de una lección') and an explicit when-not with the alternative ('para un tema concreto es mejor buscar'). It also names the downstream tools to call once a slug is obtained, which is exactly the selection guidance an agent needs.

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