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

With no annotations, the description carries the full load and does disclose the most important trait: dry-run is the default and confirm=true is required to actually upload. It also enumerates the three accepted photo sources. It omits auth requirements, size/format limits, and whether an existing photo is replaced.

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 compact sentences, front-loaded with the action and its precondition, followed by the input modes and the dry-run flag. Dense but each clause carries information; 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 5-parameter, zero-coverage, no-annotation, no-output-schema tool, the description covers inputs and the dry-run behavior but leaves gaps: no return shape for a dry run, no auth or quota context, and no failure semantics. Adequate but not fully self-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 coverage is 0%, so the description must compensate, and it does: file_id (from PUT /upload), image_path (local), image_base64, confirm (dry-run toggle) and ide_comunicacion (from the send response) are all given meaning. The 'o' listing implies the three photo sources are alternatives, though mutual exclusivity is not stated outright.

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 precise verb+resource (attach a photo) scoped to an already-created communication, and ties the required ide_comunicacion to the prior send response. This clearly separates it from the create_* siblings that build a new aviso from a photo.

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 precondition (the communication must already exist) and where the key input comes from (the send response). It does not explicitly name the alternative tools or state when NOT to use it, so it stops short of full routing 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, the description carries the full behavioral burden. It usefully discloses that the tool makes network/auth calls (requests a Keycloak token, invokes comprobarVersion), which implies side effects and a dependency on the auth service. It says nothing about failure modes, whether it mutates state, or expected latency/errors.

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 short sentences, front-loaded with the action and followed by the usage hint. Every clause contributes; nothing is padded.

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 zero-param diagnostic tool this covers the essentials of what and when, but with no output schema the description never indicates what a successful or failed check returns, which is the main thing an agent needs for a verification 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 takes zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain or compensate for.

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 ('Comprueba la cuenta de servicio') and even names the internal steps (Keycloak token, comprobarVersion), so the agent knows exactly what happens. It does not, however, differentiate itself from siblings like get_identity or set_identity, which also concern identity/auth.

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?

'Úsalo para verificar la instalación' gives a clear when-to-use scenario (installation/setup verification). No when-not conditions or named alternatives are provided, but the intended context 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?

With no annotations provided, the description carries the full burden and does well: it discloses that the default call creates NOTHING and only returns the payload, and that confirm=true is required to actually submit. It omits auth/permission requirements and any error or side-effect behavior for the real submission path.

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-loads the dry-run warning, which is the most important thing for an agent to know, and stays to a tight few sentences. No filler, though the IMPORTANT block could be marginally 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?

For a 13-parameter nested-object tool with no output schema and no annotations, the description covers the critical dry-run and identity behaviors but leaves many parameters and the return payload shape unexplained. It is adequate to avoid accidental writes but not 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 77%, so the schema already documents most parameters (kind, confirm, identity, streetCode, etc.). The description reinforces confirm and identity semantics but adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ('Crea un aviso/sugerencia') so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the sibling create_aviso_from_photo, leaving the agent to infer which creation path to choose.

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 clear operational context: default is dry-run, real creation requires confirm=true, and identity comes from storage unless overridden. It stops short of naming alternatives or stating when this tool is preferred over create_aviso_from_photo.

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 behavioral burden and does well: it discloses the four-phase state machine, that phase 3 produces a preview without sending, and the hard gate that all three of confirm/human_confirmed/preview_token are required or nothing is sent. It does not cover auth requirements, rate limits, or error 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 purpose is front-loaded in the first clause, followed by the preferred path, then the phases in order. It is telegraphic and dense but every sentence carries workflow information, appropriate for a 21-param multi-phase tool with no waste.

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 complex stateful tool with 21 params, no annotations, and no output schema, the description covers the workflow and the per-phase outcomes (need_category, need_street, preview_token) that an agent needs to drive the loop. Gaps remain around the peripheral geographic/identity fields, but the call-critical path is 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 only 57% across 21 params, but the description compensates by explaining the operational meaning of the key gate fields: service_code missing returns suggestions instead of creating, confirm=true actually sends, and human_confirmed means a human approved the preview. Several fields (x, y, kind, portal, allCity, portalBis, districtCode, streetCode, neighbourhoodCode) remain undocumented in both places.

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 names a specific verb and resource ('Aviso desde una FOTO en fases') and makes the photo-driven, phased nature explicit, which distinguishes it from the plain create_aviso sibling. It does not name create_aviso directly as the non-photo alternative, so the differentiation is implied rather than stated.

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 concrete when-to-use routing per phase (no service_code → suggest categories; no street → ask for street; confirm=false → preview; confirm=true → send) and states the preferred upload path (PUT /upload + file_id in remote, image_path under stdio). It lacks an explicit 'do not use this when...' clause or a pointer to create_aviso for non-photo cases.

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 must carry the full behavioral burden. It implies a read operation but does not state read-only behavior, authorization needs, error handling, or side effects. It only lists the returned fields.

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 efficient sentence with no wasted words and front-loads the core purpose. It is appropriately sized for a simple getter.

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 usefully names the returned fields (servicio, tipo, tema) and explains the type codes (A aviso / S sugerencia). However, it lacks usage context and does not explain when this tool is appropriate versus related siblings.

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 adds meaning by showing the service_code format as 'SERVICIO-TEMA' (service-topic), which helps an agent construct the parameter value. However, it does not fully document the parameter beyond this hint.

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 it returns detail for a serviceCode, including service, type, and topic. This is a clear resource retrieval, though it does not explicitly contrast with siblings like list_categories or suggest_categories.

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

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

No guidance is provided on when to use this tool versus list_categories or suggest_categories, nor any prerequisites or context for calling it. The description only describes the output.

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 behavioral burden and it does disclose the return payload and the null case for the unset state. It does not mention any session/auth prerequisite (relevant given the sibling check_auth) or confirm the absence of side effects beyond the read verb.

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?

A single front-loaded sentence that packs the verb, the resource, the returned fields, and the null fallback with no wasted words.

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

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

No output schema and no annotations exist, so the description must explain the return value itself, which it does by listing fields and the null case. It is nearly complete for a zero-parameter getter, missing only any auth/session precondition.

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 the schema has nothing to document and the baseline is 4. The description correctly adds no parameter guidance because none is needed.

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 ("Devuelve") plus resource ("identidad del comunicante") and it enumerates exactly which fields come back (nombre, apellidos, contacto, idioma). The read semantics are immediately distinguishable from the sibling set_identity.

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 null clause ("o null si aún no se preguntó") implicitly tells the agent this is a pre-check before asking the user, which is useful context. However, it never states when to call it, when not to, or points to set_identity as the write counterpart, so usage 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?

With no annotations, the description carries the full burden. It does disclose one useful behavioral trait — that each returned topic carries a serviceCode in 'SERVICIO-TEMA' format — but says nothing about it being a read-only operation, the return shape, ordering, or whether the catalog is static.

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 compact sentences with no padding, leading with the resource and then the key payload detail (serviceCode). Efficient, though the opening noun phrase is slightly opaque.

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 listing tool with no output schema, the description only partially covers the return contract: it explains the serviceCode convention but not the category fields, count, or ordering an agent would receive.

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 the baseline is 4; there is nothing for the description to clarify beyond the schema, which is already complete at 100% coverage for an empty object.

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 names the resource ('Servicios y temas de avisos (categorías municipales)') and implies enumeration, but never states the action of listing or how it differs from the sibling tools get_category and suggest_categories. An agent can infer the domain but must guess the exact behavior relative to its siblings.

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 hints at the downstream use case by noting each topic's serviceCode 'SERVICIO-TEMA' is used 'para crear avisos', which implicitly points to create_aviso. However, it gives no explicit when-to-use, when-not, or comparison against get_category/suggest_categories.

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 reveals that results default to the caller's saved phone/email and that these can be overridden, which is useful, but it says nothing about read-only vs. write semantics, permissions, ordering, or result format 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?

A single sentence that front-loads the resource and then the filtering behavior. It is appropriately sized with little waste, though the parenthetical makes it slightly dense.

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 no annotations and no output schema, the description is too thin: it never states the operation type, what an 'aviso' contains, ordering/pagination, or the return shape. The agent is left to infer most of what it needs to invoke the tool 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 0%, so the description must compensate, and it partially does: it explains that userPhone/userEmail act as filters based on saved values and that they can be overridden per call. It still omits expected formats and whether both are optional, but it adds real meaning beyond the bare 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 phrase 'Comunicaciones del comunicante' identifies the resource (the caller's communications/avisos) but uses a noun phrase with no explicit verb, so the agent must infer that this is a retrieval/list operation. It does distinguish the tool from the create_* siblings by scoping to the caller's own records, but the action itself is only implied by the filtering clause.

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?

There is no statement of when to use this tool versus create_aviso, create_aviso_from_photo, or any sibling. The only usage hint ('se pueden sobrescribir para la llamada') explains parameter override behavior rather than selecting this tool over an alternative. 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?

No annotations exist, so the description carries the full burden. It usefully discloses the input convention (lon/lat order, WGS84) and the shape of the result (nearest street plus portal), but says nothing about no-match behavior, result precision, or whether a single or multiple candidates are returned.

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?

A single sentence with the resource, the coordinate convention, and a concrete use case, all front-loaded 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 two-parameter read tool with no output schema, the description covers the inputs and the gist of the return value, but leaves the response format and failure cases undefined. It is adequate but not fully self-contained.

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%, and the schema itself only labels both parameters as bare numbers. The description compensates by fixing the argument order (lon first, then lat) and the coordinate system (WGS84), which is exactly the information an agent would otherwise guess wrong.

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 resource and scope: it returns the nearest street and street number for a set of coordinates, and it names the coordinate system (WGS84). Combined with the tool name, an agent can distinguish it from forward-looking siblings like search_street, though the description never uses an explicit verb such as 'returns' or 'finds'.

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 only implied via the example '(p.ej. del GPS de la foto)', which hints at the photo-geotagging scenario. There is no explicit statement of when to prefer this over search_street or what to do when coordinates are unknown or outside coverage.

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 usefully discloses that the tool returns multiple candidates (plural implies fuzzy/partial matching) and enumerates the returned fields, but gives no read-only confirmation, matching tolerance (accents, abbreviations), or result limits.

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: the purpose leads, the return shape follows. Nothing is wasted and the ordering 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 the return fields (TECA_COD_CALLE, portales, barrio/distrito, X/Y), which an agent needs to interpret results. It leaves only minor gaps around matching behavior and authentication 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?

Only one parameter, fully documented in the schema (100% coverage) with an example ('Gran Via'). The description adds no formatting guidance 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 and resource in Spanish: 'Busca una calle en el callejero municipal' (searches a street in the municipal street directory), and the second sentence enumerates the returned fields. It is clear what the tool does, though it never explicitly contrasts itself with the nearby reverse_geocode sibling.

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

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

No indication of when to use this tool versus alternatives such as reverse_geocode (coordinate-based lookup) or other search tools. It also doesn't state prerequisites for getting useful results (e.g., partial vs. exact street names).

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 behavioral burden. It discloses validation rules (name and first surname required; phone or email required) and the reuse pattern, but omits authentication requirements, error behavior, and whether calling it again updates existing data.

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: the first states purpose and usage context, the second lists validation constraints. Front-loaded and free of 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?

For a mutation tool with no annotations and no output schema, the description covers purpose, validation, and basic usage context. It lacks details on permissions and update semantics, but is largely sufficient for correct invocation.

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 restates the required fields and the conditional phone/email requirement, which is already documented in the schema, adding no new syntax or format details.

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 ('Guarda') and resource ('identidad del comunicante'), clearly distinguishing it from the sibling get_identity. The added note on being asked once after installation further specifies the intended use.

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?

Provides clear context: it is asked once after installation and reused, implying a one-time setup call. However, it does not explicitly mention alternatives like get_identity or when not 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?

No annotations are provided, so the description carries the full behavioral burden. It does not say whether results are ranked/scored, whether it is a read-only suggestion vs. an assignment, whether auth is required, or how many codes come back — real gaps for a tool whose whole output is a suggestion set.

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?

One tight sentence with the purpose front-loaded and the example appended, no filler. It is slightly under-specified rather than over-long, so length itself is not the problem.

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 tool with no output schema and no annotations, the description conveys the core idea (free text in, serviceCodes out) but omits the shape of the response and the exact nature of the hint, leaving the agent to guess at call details.

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 0% and the single 'hint' parameter has no schema description, so the description must compensate. It partially does by stating the input is free-text words and giving an example, but it does not clarify language, length, or whether keywords or full sentences are expected.

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 (sugiere/suggests) and resource (serviceCodes) along with the input modality (por palabras). It clearly describes a lookup-by-free-text purpose, though it never differentiates itself from the related list_categories/get_category siblings.

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 concrete example ('cartones apilados en acera') implies when the tool is useful — when the agent has a descriptive free-text hint rather than a known code — but there is no explicit when-to-use statement or routing against list_categories or search_street.

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