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

Annotations already declare readOnlyHint and openWorldHint, so safety profile is covered. The description adds that it returns a narrative guide rather than raw data, which is useful behavioral context, but does not describe format, length, or pagination of the returned guide. With annotations covering the safety angle, a 3 is appropriate.

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 tightly packed sentences with no filler, front-loading the core purpose and the only available option. Every phrase earns its place.

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

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

Given a read-only, no-required-params tool with full schema coverage and no output schema, the description is nearly complete. It could mention that the guide is static or versioned, but nothing critical for an agent 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 both parameters have detailed enum descriptions, so the schema already documents semantics fully. The description only mentions the available flow value, which is already in the schema. Baseline 3 is correct when 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 (returns the narrative guide of an end-to-end API flow) which is distinct from siblings like get_endpoint or search_docs. It even names the currently available flow ('test-to-live') and what it does. However it does not explicitly contrast with siblings, which would be needed for a 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?

It clearly signals when this tool is useful by stating the only flow available and calling it 'el flujo recomendado', implying its use for end-to-end guidance rather than single-endpoint lookups. It does not explicitly state when NOT to use it (e.g., for individual endpoints).

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 cover read-only and open-world nature, so the base bar is lower. The description adds valuable behavioral context: it's a stable public contract shared across API versions, and advises switching on the code. It also implies the catalog is comprehensive. Missing explicit statement about rate limits or caching, but sufficient given 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?

Two sentences, front-loaded with what the tool does and what it returns, then adds the shared-contract caveat. 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?

Complete for a read-only lookup tool. With no output schema, the description appropriately lists the return fields, saving the agent from inference. It could optionally mention if results are paginated or if errors are returned for unknown codes, but for a simple catalog lookup it's sufficiently complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters (including description, case-insensitivity, and version enum with default). The description only adds the example input format and a reminder that code is case-insensitive via 'ej. E_RATE_LIMITED' and the switch note, but doesn't significantly expand on the parameters beyond schema. 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 clear verb+resource ('explica un código de error') and elaborates on exactly what is returned: HTTP status, when it occurs, doc URL, and emitting endpoints. Distinguishes itself from siblings like get_endpoint or search_docs, which are about endpoints and docs, not error codes.

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 specific context: input is the 'code' field from an RFC 7807 body, with an example. However, it doesn't explicitly state when-not-to-use or name alternatives (e.g., 'para buscar códigos por texto, usá search_docs'). Context is clear but lacks alternative routing.

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 and openWorldHint=true, so the description only needs to add context beyond that. It usefully warns that API key values are placeholders and that output matches the website snippet, which preempts an agent treating the snippet as runnable with real credentials.

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 short sentences, front-loaded with the return value, then identification method, then the credential caveat. No filler, though the phrase 'idéntico al de la web' is slightly decorative.

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 states that the return is a ready-to-use code snippet and notes the placeholder credentials. Version defaults and legacy guidance are already covered in the schema, so the remaining gap is minor.

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 the genuinely useful fact that identification is an either/or choice between operationId and method+path, a constraint the schema leaves implicit. The lang enum values are left to the schema, which is fine.

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 ('Devuelve un snippet de código listo para usar') plus the exact output formats (curl, JavaScript fetch, Python requests), which no sibling tool produces. An agent can distinguish it from get_endpoint or get_openapi 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?

Explains the two accepted identification modes ('Identificá el endpoint por operationId o por method+path'), which is real routing guidance. It does not say when to prefer this over siblings like get_endpoint or get_openapi, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the returned object includes idempotency, credit cost, error codes, and documentation prose, which is useful context beyond the annotations, but it does not describe pagination or data freshness.

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?

It is two sentences, front-loaded with the returned payload and followed by the identification instructions. The field enumeration is slightly dense but each item earns its place by telling the agent what to expect in the response.

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 read-only introspection tool with no output schema, the description adequately explains what is returned and how to address the resource. It could note what happens if the endpoint is not found or when v1 is not available, but otherwise it is complete enough to invoke 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% and all four parameters are documented in the schema with examples and enums. The description reinforces the identification patterns but adds no syntax beyond what the schema already 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?

The description states a specific verb and resource ('Devuelve el detalle completo de un endpoint') and enumerates the exact payload fields (parámetros, request body, respuestas, scope, costo, idempotencia, errores, prosa). It is unmistakably distinct from sibling list_endpoints, which it references.

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 states when to use this tool by giving the two identification modes (operationId, or method+path) and points to list_endpoints for discovery. It lacks explicit 'when not to use' guidance (e.g. for flows or errors, see describe_flow/explain_error), which other siblings cover.

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 and openWorldHint=true, so the safety profile is covered. The description adds that the payload equals the canonical document at the api-docs URL, but says nothing about payload size, cost, or caching behavior – meaningful for a tool that returns an entire spec.

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, zero waste: the what and scope come first, the canonical-URL reference and use cases follow. Nothing could be removed without losing 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?

With no output schema, the description does carry the return burden and adequately says it returns the complete OpenAPI 3.1 document. It omits any note on payload size or when fetching the whole contract is preferable to per-endpoint calls, a minor gap 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 coverage is 100% and the single version parameter already carries a full inline description with enum guidance (v2 recommended, v1 for legacy). The description's 'v2 por default' restates the schema rather than adding format or edge-case detail, so 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+resource ('Devuelve el documento OpenAPI 3.1 completo de la API') with explicit scope (full spec, not a fragment), which distinguishes it from fragment-oriented siblings like list_endpoints and get_endpoint. It stops short of naming an alternative directly, so sibling differentiation is strong but implicit.

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 concrete use cases ('Útil para generar clientes o cargar el contrato entero'), which tells the agent when this tool is the right choice over endpoint-level siblings. No explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds useful context beyond that: the tool returns a metadata index per endpoint (scope, key environment test/live/any, idempotency, credit cost) and instructs the agent to read the returned api_version field to confirm which doc version was served. Pagination or size limits are still undisclosed.

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 core purpose, and the returned-field enumeration earns its length by telling the agent what the index contains. The field list is dense but functional; nothing is wasted.

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-optional-parameter read-only index with no output schema, the description covers purpose, scope, returned content, version default, and how to verify the doc version from the response. An agent has everything needed to call it correctly without opening the 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?

Schema coverage is 100% and the single optional 'version' parameter is fully documented in the schema, including the default and the legacy caveat. The description only restates the v2 default, adding no syntax or semantics beyond the schema, so 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+resource ('Índice de todos los endpoints de la API pública de Automeli') and even enumerates the per-entry fields (method, path, summary, scope, key environment, idempotency, credit cost), so an agent immediately knows what it gets. It implicitly contrasts with get_endpoint by saying 'todos los endpoints', but never names that sibling or get_openapi explicitly, so it falls just short of full differentiation.

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?

'Punto de partida para descubrir la API' gives clear context for when to reach for this tool instead of a detail lookup. It stops short of naming alternatives (get_endpoint, get_openapi) or stating exclusions, so there is no explicit 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?

Annotations already declare readOnlyHint and openWorldHint, lowering the disclosure bar. The description adds useful context beyond them: results are returned ranked with type, title, a reference (operationId / error code / URL) and an excerpt, and the search is lexical rather than semantic. No pagination or ranking-order caveats, but the core behavior is well conveyed.

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

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

Three sentences, front-loaded with the search scope, then return shape, then example intents. Efficient and free of filler, though the example-query list is slightly loose prose.

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, but the description compensates by describing the result fields and ranking, and the parameter schema is fully documented. An agent has enough to call it and interpret results; only sibling routing is left implicit.

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 query, limit, and version (including the v2-default / v1-legacy guidance and enum). The description adds nothing parameter-specific beyond the return fields, 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+resource: 'Búsqueda léxica en toda la documentación' and enumerates the coverage (endpoints, errores, guías, flujos). The lexical qualifier helps an agent distinguish it from semantic or targeted lookups, but it never names or contrasts any sibling (e.g., get_endpoint or explain_error) for direct lookups.

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?

"Útil para '¿cómo publico un producto?', 'rate limit', 'cursor', 'idempotencia'" gives concrete query intents, which clarifies when to reach for this tool. It stops short of stating when NOT to use it or which sibling covers narrower needs (single endpoint detail, error explanation).

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