Subastech — subastas judiciales de inmuebles (BOE)

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

The annotations already establish non-readOnly, non-destructive, and idempotent behavior, so the description adds useful context beyond them: the operation is scoped to the user's own alert, does not delete it, and requires a verified account with the alertas:write scope. No contradiction with the 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 short sentences, front-loaded with the core action and followed by the auth requirement. Every sentence adds value and 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 simple two-parameter tool with an output schema and annotations, the description covers purpose, ownership, non-destructiveness, and authentication requirements. The only notable omission is explicit parameter value semantics, but the simplicity of id and activa makes this a minor gap rather than a completeness failure.

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 carries the burden, but it only partially compensates: 'Activa o pausa' explains the semantic effect that the boolean activa field likely controls, and 'una alerta tuya' implies id identifies an owned alert. However, it does not explicitly map true/false to activate/pause or define the id parameter, so the agent must infer the mapping.

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 action (activate or pause) on a specific resource (one of the user's alerts) and explicitly notes it does not delete the alert, which distinguishes it from alertas_eliminar and other alert siblings. The title and description align and leave no ambiguity about what the tool does.

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 gives clear context: it is for activating or pausing an alert the user owns, not for deleting it, and it states a prerequisite (verified account with alertas:write scope). It does not explicitly name alternatives like alertas_editar or alertas_eliminar, but the intended use is evident from the sibling names and the action described.

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 convey this is a non-read-only, non-destructive mutation, and the description adds genuine behavioral context beyond them: the auth scope requirement, the confirmation-email side effect, and plan-dependent limits. It does not contradict the annotations (creating aligns with readOnlyHint=false and destructiveHint=false). It could go further on failure/validation behavior, but the disclosed side effects are a solid addition.

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 tight sentences, each earning its place: purpose first, then prerequisites/side-effects/limits, then the preview router. Front-loaded and zero waste for a tool of this 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 complexity — 6 params, 5 required, a nested criterios object with 12 sub-properties, and an output schema — the description covers the essential operational envelope: auth prerequisites, the email side effect, plan limits (with a pointer to ajustes), and the preview workflow. The fine-grained plan-dependent parameter behaviors are left to the schema, which already documents them, so nothing critical is missing for an agent to invoke it safely.

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 67%, and the schema itself is rich — it already documents plan-gating (cadencia 'instant' requires Pro, scoreMin/discountMinPct require Pro, 'inapp' always in canales). The description adds only a category-level summary (criterios, tipos, cadencia, canales) and a generic pointer to plan limits via ajustes, which mostly echoes the schema. It does not compensate for the undocumented params (quiet_hours structure, nombre limits), so a mid-range 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 opens with a specific verb+resource: "Crea una alerta de subastas" (creates an auction alert) and enumerates the alert's components (criterios, tipos de aviso, cadencia, canales). This clearly differentiates it from siblings like alertas_listar, alertas_eliminar, and alertas_activar, which cover other lifecycle stages.

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 gives explicit operational context: verified account with scope alertas:write is required, a confirmation email is sent, and limits depend on the plan (referencing ajustes). It also names an explicit alternative workflow — "Previsualiza antes con alertas_previsualizar" — telling the agent to preview before creating. It stops short of a full when-not matrix against all alert siblings (e.g., editing via alertas_editar), so it earns 4 rather than 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 establish this is a non-read, non-destructive, idempotent mutation. The description adds useful behavioral context beyond that: the auth scope requirement (`alertas:write`) and the side-effect statement 'No envía correo'. This helps the agent understand what the operation does and does not trigger.

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

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

The description is two sentences with no filler. The first sentence states the action and scope of fields; the second adds the key prerequisites and behavioral note. Information is front-loaded and every sentence 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 the rich input schema, output schema, and annotations, the description is nearly complete for an agent to select and invoke the tool. It covers the purpose, the affected resource, required scope, and a notable side-effect. A small gap is that it does not clarify whether the update is partial or a full replacement of the alert configuration.

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 57%, so the schema carries much of the parameter documentation. The description adds a high-level grouping of fields (nombre, criterios, tipos, cadencia, canales, horas de silencio) but does not explain semantics beyond what the schema already provides. It partially compensates for the uncovered top-level parameters like `quiet_hours` by naming the concept.

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 a specific verb and resource: 'Modifica una alerta existente' (modify an existing alert), followed by a list of editable fields. This clearly distinguishes it from sibling tools like alertas_crear (create) and alertas_eliminar (delete) through the word 'existente'.

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 makes clear this is for editing an existing alert, which implies it should not be used for creation or listing. It also states a concrete precondition: requires a verified account with scope `alertas:write`. It does not explicitly name alternatives or exclusion cases, but the usage context is reasonably clear.

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 mark this as destructive and non-read-only, but the description adds value with 'de forma permanente' (irreversibility) and the specific auth scope 'alertas:write'. These details go beyond what the annotations provide.

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

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

The description is two short sentences with no filler. The action and permanence are front-loaded, and the auth requirement is stated separately and efficiently.

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 delete operation, the annotations cover safety and idempotency, and the output schema covers return values. The description covers purpose, ownership, permanence, and auth. The only real gap is not explicitly stating that the id parameter is the identifier of the alert to delete.

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 schema only defines id as a string of 1-64 characters, and the description does not explain what the id parameter refers to or where to obtain it. With 0% schema description coverage, the description should compensate, but it leaves id semantics entirely to inference from the tool name and property name.

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 action ('Elimina'), the target resource ('una alerta tuya'), and the permanent nature of the operation. This clearly distinguishes it from sibling tools like alertas_editar, alertas_activar, or alertas_listar.

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 context is clear: use this tool to permanently delete one of the user's own alerts, and the auth requirement is explicitly stated. It does not explicitly name alternatives or say when not to use it, but the intended use is evident from the sibling tool set.

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 destructiveHint, so the safety profile is covered. The description adds meaningful context by specifying the authentication requirement and OAuth scope (alertas:read), which is not expressed in the annotations and is useful for an agent deciding whether it can invoke the 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?

Two short sentences deliver all necessary information without redundancy. The main capability is front-loaded, and the auth requirement is stated concisely as an additional condition.

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 that the tool has no parameters, a rich output schema, and annotations covering side effects and idempotency, the description is complete for an agent to select and invoke it correctly. Mentioning the required scope is the only extra contextual detail needed, and it is present.

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

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

The tool has zero parameters, so the baseline is 4. The description adds value by indicating what data the response includes, though it does not need to explain parameter semantics since there are none.

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?

Describes a specific action (listar) over a concrete resource (alertas de subastas) and enumerates the returned aspects: criterios, tipos de aviso, cadencia, canales y estado. This clearly differentiates it from sibling tools like alertas_crear, alertas_editar, and alertas_eliminar, which perform different operations.

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 makes the use case clear: retrieving the current user's auction alerts with their settings. It does not explicitly name excluded alternatives or state 'use this instead of X', but the contrast with mutation-oriented siblings is evident from the verb and resource.

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

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

The annotations already mark the operation read-only and idempotent; the description adds valuable behavioral detail: Pro-plan-dependent criteria are silently ignored and reported in `ajustes`, and warnings include an applicable `fix`. It also states the OAuth scope requirement. No contradiction 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?

Three dense sentences front-load the purpose, then state the prerequisite and the non-obvious Pro-plan behavior. No filler or repetition of schema information.

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

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

For a preview tool, the description covers purpose, triggering context, auth scope, plan-dependent behavior, and warning output. The existing output schema and nested input schema handle the remaining structural detail.

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 top-level `criterios` parameter lacks a schema description (0% coverage per signals), and the description only names two advanced fields (`scoreMin`, `discountMinPct`) with their Pro-plan fallback. However, the nested schema carries rich per-field descriptions, and the description's context makes the role of `criterios` clear, so this is minimally viable rather than a complete 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 names a specific verb and resource: previewing an alert before creation, and states exactly what it returns—matching auction count, a sample, and warnings with fixes. This clearly distinguishes it from siblings like alertas_crear, alertas_activar, and alertas_listar, which all have different operations.

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 a clear trigger context—'Antes de crear una alerta'—and a prerequisite (account with scope alertas:read). It does not explicitly name alternatives or say when not to use it, so it stops one step 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?

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds meaningful behavior beyond that: the required auth scope, the plan paywall with the concrete `locked`/`upgradeUrl` response on lower plans, and the fact that calls do not consume quota. This materially helps an agent predict whether a call will succeed and what it will cost.

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 with zero filler: the first states the core purpose, the second covers prerequisites and plan-gated behavior, and the third notes quota usage. Every sentence earns its place, and the most decision-relevant information 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 a single fully-documented parameter, an output schema available, and annotations covering the safety profile, the description covers the remaining context: purpose, auth scope, plan requirements, the locked fallback, and quota behavior. The only notable gap is guidance on choosing this tool over overlapping siblings like `informe`, which is a minor omission for an otherwise complete definition.

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% — the single required `id` parameter is fully documented in the schema as the 10-character public auction identifier with a validation pattern. The description adds no parameter-specific semantics beyond what the schema already provides, 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?

The description states a specific output — a viability verdict ('Veredicto de viabilidad') with four named analytical axes (cargas, posesión, rentabilidad, titularidad) applied to an auction. This is a specific resource plus implicit verb, clearly distinct from a plain auction lookup, though it does not explicitly name or contrast a sibling such as 'informe' or 'subasta'.

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 gives clear context for when the tool is usable: it requires an authenticated account with scope `informes:read` and a Pro-or-higher plan, and specifies the fallback behavior on lower tiers (Radar/Starter returns `locked` with `upgradeUrl`). It does not provide explicit when-not-to-use guidance or point to alternative sibling tools, but the prerequisites are stated unambiguously.

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 the operation is read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it is public and requires no account, and it explains that results differ depending on authentication—only current catalog entries without an account, but archived ones too when authenticated. This is substantive, nontrivial behavior the agent could not infer from annotations or 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?

Two sentences, each earning its place: the first explains what the tool does and its accepted inputs, and the second provides the auth-dependent behavioral nuance. No filler, no redundancy with annotations, and the key action 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?

The single parameter is fully documented in the schema, the annotations cover safety, the output schema exists so return values need not be explained, and the description adds the only missing behavioral context—public access and archived-record visibility. Nothing essential is left out for an agent to invoke this 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 100%, so the baseline is 3. The tool description repeats the code types and the 1-5 limit already present in the schema description, adding no new parameter-level detail such as format, matching semantics, or case sensitivity. It does not compensate 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 and resource: 'Localiza subastas del BOE a partir de códigos.' It also enumerates the exact code types accepted (referencia catastral, CRU, IDUFIR, identificador BOE), which clearly distinguishes this tool from broader search siblings like buscar_subastas or search.

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 gives clear usage context: this tool is for looking up auctions by structured codes rather than free-text queries, and it clarifies account-dependent behavior. It does not explicitly name alternative tools or state when not to use it, so it misses the top bar for explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint true, and the description adds substantial behavioral context on top: plan-gated fields return `locked` with `upgradeUrl`, `orden: score` silently falls back to `recent` and `solo_viables` is ignored (with a `degradado` field), and there is a 20-per-page cap. This gives an agent an accurate model of what the response will contain across account tiers. No contradiction 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?

Four dense sentences with zero filler: the purpose and filter scope are front-loaded, followed by access model, plan-gated data behavior, degradation behavior, and pagination cap. Every clause carries operational information an agent needs.

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 15-parameter tool with 100% schema coverage, an output schema, and safety annotations, the description covers the remaining critical ground: access tier, exactly which derived fields are gated, how gating manifests in responses (`locked`/`upgradeUrl`/`degradado`), and pagination limits. Nothing an agent needs to call and interpret this search 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 individual parameter meaning is already documented; the description adds cross-parameter, plan-dependent semantics that the schema cannot express, such as `orden: score` degrading to `recent` and `solo_viables` being ignored without Pro. It also bundles the two zone parameters as 'zona (bbox o radio)', helping an agent see that `bbox` and `cerca` are alternatives for the same filter intent.

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 ('Busca subastas judiciales de inmuebles del BOE') and enumerates eight filter dimensions (provincia, municipio, tipo, precio, superficie, texto libre, zona, estado). This scope clearly distinguishes it from siblings like `subasta` (singular) and `buscar_por_codigo`, whose names imply narrower lookups. The access model ('Pública, sin cuenta') further pins down its role as the open multi-filter search.

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 gives clear context: it is the public, account-free search over BOE auctions, and it explicitly explains plan gating (Pro required for scoring, veredicto, cargas, ROI, valoración, intervinientes) plus degraded behavior without a plan. However, it never names sibling tools or states explicit when-not-to-use conditions, so exclusion guidance is implied rather than stated.

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 indicate destructive and idempotent behavior, and the description adds useful context beyond them: it releases any order draft, has no effect on completed/canceled sessions, and requires both meta fields. There is no contradiction with the 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?

Three concise, purposeful sentences with no filler. The action is front-loaded, the edge-case behavior is stated, and the required metadata is called out. Every sentence 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?

For a destructive idempotent operation with an output schema, the description covers purpose, effect, no-op cases, and prerequisites. The only meaningful gap is the undocumented `id` parameter, which prevents a perfect score.

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, but it only explains the meta requirements and never describes the required `id` parameter. The description adds no meaning for `id`, leaving the agent to infer that it is the checkout session identifier from the tool name and context.

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 a specific action ('Cancela una sesión de checkout UCP abierta') and its concrete effect ('libera cualquier borrador de pedido'). It also distinguishes itself from related checkout tools by focusing on cancellation and explicitly noting that completed or canceled sessions are unaffected.

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 makes the intended use clear: cancel an open UCP checkout session. It also provides an implicit exclusion ('Una sesión completada o cancelada no cambia') and states required prerequisites. It does not explicitly name alternatives like complete_checkout, but the context is otherwise strong.

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

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

The description goes well beyond the annotations by disclosing a charging side effect, instant delivery, escalation to requires_escalation with continue_url, and the no-charge case for a report included in the plan. It also calls out the required idempotency-key metadata. This is rich, honest behavioral disclosure.

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

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

The description is three dense sentences with no filler. The main purpose is front-loaded, followed by the conditional payment behavior and metadata requirement. Every sentence contributes useful 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?

Given the tool's complexity and the presence of an output schema, the description covers the essential behavioral paths, the free-report edge case, and the idempotency requirement. Nothing critical is missing for an agent 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 0%, so the description must add parameter meaning, and it does: it explains the payment.instruments structure, the important handler_id and credential.token fields, and the need for meta['idempotency-key'] plus meta['ucp-agent']. It does not discuss the id parameter or checkout.signals, but these are less critical for invoking the tool correctly.

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 a specific verb and resource ('Completa una sesión de checkout UCP') that clearly distinguishes the tool from siblings like create_checkout, update_checkout, and cancel_checkout. It also states the main behavioral outcomes, so an agent can immediately tell what this tool is for.

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 gives clear operational context: when a Stripe Shared Payment Token is present, the session is charged and delivered; otherwise it escalates. It does not explicitly name alternatives or exclusions, but the first sentence combined with the sibling list makes the intended use clear enough.

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 are all false and thus provide little signal, so the description carries the burden. It discloses meaningful behaviors: buyer account creation/linking with an email access link, charging conditions for nota-simple, browser completion for subscriptions, and the required ucp-agent meta. It does not explicitly clarify charge timing for informe items or create-vs-complete side effects, which is a moderate gap.

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 dense but every clause earns its place: purpose, version/date, product catalog, pricing, constraints, buyer behavior, return value, and authentication requirement. It is front-loaded with the core action and avoids fluff.

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

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

The description covers the essentials needed to call create_checkout: product identifiers, required meta, buyer behavior, and return shape. Given the existing output schema and sibling tools, it is mostly complete, but it does not mention the checkout completion/cancellation flow or payment instrument usage, which would help an agent navigate the full workflow.

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 schema description coverage at 0%, the description compensates strongly: it enumerates exact item.id formats with prices, specifies one product/quantity 1, explains buyer.email account behavior, and requires meta['ucp-agent'] with a profile URL. This adds substantial meaning beyond the raw JSON Schema.

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

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

States a specific action ('Crea una sesión de checkout UCP') and a concrete resource scope: buying informes, nota simple, or a Subastech subscription. The product list and prices make the purpose unmistakable and differentiate it from sibling checkout tools like complete_checkout, cancel_checkout, and get_checkout.

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 for when to invoke it: creating a checkout for one of the enumerated products. It also states constraints (one product per session, quantity 1, buyer email required). However, it never names or contrasts with sibling tools such as complete_checkout or cancel_checkout, so the when-not-to-use guidance is left implicit.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond the annotations: no authentication is required, property-type values are exact filter values, and municipality search results use `provincia:municipio` keys. No contradiction with annotations exists.

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 short, dense, and front-loaded with the main outputs. Every sentence adds information: what data is available, exact filter values, the public/no-account nature, and the explicit exclusion of market statistics. There is no filler or repetition of schema content.

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 statistics tool with two optional parameters, a complete output schema, and clear annotations, the description is sufficiently complete. It covers authentication requirements, scope, exact filter hints, and the key alternative tool. Nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage for both parameters is 100%, including the enum for `estado` and the minimum-length requirement for `municipio_q`, so the schema already handles parameter documentation. The description adds some contextual value, such as the `provincia:municipio` key format, but this mostly describes output behavior rather than deepening the meaning of the input parameters themselves.

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 enumerates what the tool returns: catalog totals, provinces with active/historical auctions, property-type values to use as filters, and municipality search results. It also distinguishes itself from the sibling tool `mercado` by explicitly excluding market statistics. This is specific enough for an agent to know exactly what it offers.

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 states that the tool is public and requires no account, which is a clear precondition for use. It also explicitly says what it does NOT include and routes the user to `mercado` for market statistics, giving an explicit alternative and when-not-to-use condition.

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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: it is public, requires no account, uses a human-curated knowledge base, and explicitly states that no language model is involved. This helps set accurate expectations about how results are generated.

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 one well-structured sentence, front-loaded with the core purpose and followed by useful clarifying details. Every clause adds value: scope, examples, source, access, and generation behavior.

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?

This is a low-complexity, single-parameter tool with full schema coverage, a read-only annotation profile, and an output schema. The description and schema together cover the tool's purpose, usage, access constraints, and behavioral expectations. Nothing essential 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 one parameter 'pregunta' is already described with an example. The description repeats some example concepts but adds no new parameter-level semantics beyond what the schema already provides.

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 ('Explica') and the resource ('un concepto de las subastas judiciales en España'), with concrete examples. The phrase 'desde la base de conocimiento de Subastech, redactada por personas' distinguishes it from search, analysis, and report tools.

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 gives clear context: use it for conceptual questions about Spanish judicial auctions, e.g., 'depósito', 'cargas', 'cesión de remate'. It does not explicitly state when not to use it or name alternative tools, but the intended use case is reasonably clear.

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 convey idempotency and non-destructiveness. The description adds valuable behavioral context beyond annotations: authentication requirements, required OAuth scope, and plan-based restrictions on which subastas can be saved. No contradiction with annotations is present.

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 filler. The primary action is front-loaded, and the second sentence efficiently packs authentication, scope, and plan restrictions.

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

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

For a single-parameter tool with an output schema and annotations covering safety and idempotency, the description covers the remaining critical context: auth, scope, and plan-based feature gating. Nothing essential 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 input schema fully documents the single parameter `id` with type, pattern, and description. The tool description adds no additional parameter-specific semantics, so the baseline of 3 applies because schema coverage is 100%.

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 the specific action and resource: 'Guarda una subasta en tus favoritos.' The verb 'guarda' and the target 'favoritos' clearly distinguish this tool from siblings like favoritos_listar and favoritos_quitar.

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

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

The description provides clear usage conditions: an account is required, the scope `favoritos:write` is needed, and plan limitations are specified ('Radar y Starter solo pueden guardar subastas activas'). It does not explicitly name alternative tools for related operations, but the context is clear enough.

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?

Beyond the annotations already marking the operation as read-only, idempotent, and non-destructive, the description discloses authentication scope and a paywall: scoring, verdict, charges, ROI, valuation, and participants require Pro, and locked items return `locked` with `upgradeUrl`. This is valuable behavioral context an agent cannot infer from annotations alone.

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 compact and front-loaded: purpose first, then auth, then plan-gated behavior. Every sentence earns its place, and the dense list of gated fields is necessary to explain when `locked` may appear 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?

Given there are no parameters and an output schema exists, the description covers the only operational unknowns: account/scope requirements, Pro-plan restrictions, and locked/upgradeUrl behavior. Nothing essential is missing for an agent 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?

The input schema has zero properties, so schema coverage is 100% and no parameter explanations are needed. With no parameters, the baseline is 4, and the description appropriately adds nothing about parameters.

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 exact resource, 'Subastas que has guardado como favoritas,' and the title supplies the list verb, making the operation unambiguous. This clearly separates it from sibling tools like favoritos_anadir/quitar (which modify favorites) and buscar_subastas (which searches broadly).

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 explicit prerequisites: an account with the `favoritos:read` scope, and a Pro or higher plan for certain fields. This gives an agent clear preconditions for calling the tool. However, it does not name alternatives or explicitly state when not to use this tool versus a sibling, stopping 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?

Las anotaciones ya indican destructiveHint=true y readOnlyHint=false, y la descripción no contradice eso. Añade valor al especificar el requisito de cuenta y el scope 'favoritos:write', que no están en las anotaciones ni en el esquema.

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?

La descripción es una sola oración directa y sin relleno. Comunica la acción y el requisito principal de forma eficiente, con la información clave al frente.

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?

Para una herramienta con un solo parámetro, esquema completo, anotaciones de seguridad y esquema de salida, la descripción es suficiente. No faltan elementos críticos para que un agente seleccione y use correctamente la herramienta.

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?

El esquema cubre el 100% del parámetro 'id', incluyendo formato y descripción. La descripción no agrega detalles adicionales sobre el parámetro, solo confirma que se refiere a una subasta, por lo que se mantiene en el nivel base.

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?

La descripción usa un verbo específico ('Quita') y un recurso claro ('una subasta de tus favoritos'), lo que identifica exactamente la operación. Se distingue fácilmente de las herramientas hermanas favoritos_anadir y favoritos_listar por el verbo y el contexto.

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?

La descripción deja claro que sirve para quitar una subasta de favoritos, por lo que el uso es deducible. Sin embargo, no menciona explícitamente cuándo no usarla ni señala alternativas como favoritos_anadir o favoritos_listar; solo indica que requiere cuenta.

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 destructiveHint=false. The description adds non-obvious behavior beyond the annotations: gated content returns `locked` with `upgradeUrl`, and output is served as Markdown from public BOE data. This meaningfully helps an agent anticipate paywall-driven responses.

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 front-loaded sentences: the first states the core action and return fields, the second covers access requirements and locked behavior. The enumeration of gated fields (scoring, veredicto, cargas, ROI, valoración, intervinientes) is slightly long but earns its place by telling the agent exactly what to expect.

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

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

For a single-parameter read-only tool with full annotations and an output schema, the description covers access level, data source, output format, and paywall gating. Nothing an agent needs to call it correctly — or to set expectations about locked fields — 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%: the single `id` parameter is already documented as returned by `search` or a record URL. The description confirms the lookup key used but adds no format, syntax, or edge-case detail beyond what the schema already provides, 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?

The description states a specific verb and resource: 'Lee una ficha de subasta por `id`' — reads a single auction record by id. It enumerates the return fields (`id`, `title`, `text`, `url`, `metadata`), and the 'compatible con la búsqueda profunda de ChatGPT' plus public-BOE-data focus clearly differentiates it from siblings like `analisis_subasta`, `informe`, or `subasta`.

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?

Clear usage context is provided: 'Pública, sin cuenta' signals no authentication prerequisite, and the schema param description tells the agent the `id` comes from `search` or a record URL, implying the search→fetch workflow. The locked-fields paragraph implicitly warns this tool won't satisfy requests for scoring, verdict, or ROI, but it never names the alternative tool to use for those.

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 non-destructive; the description adds the required meta['ucp-agent'] profile format and the specific state/return-field behavior. No contradiction 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?

Two sentences, front-loaded with the action and resource, with the state list and auth requirement packed efficiently. 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?

Given the read-only annotations, output schema, and existing sibling names, the description covers the essential call context: what it returns, possible states, and the required meta field. Nothing critical is missing for a caller.

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 compensates by explaining that id identifies a checkout session and by specifying the required meta['ucp-agent'] profile URL. It does not detail optional request-id/idempotency-key, but those are secondary for a read operation.

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 ('Devuelve') and resource ('estado actual de una sesión de checkout UCP por id'), enumerates the possible state values, and names the returned fields. This clearly differentiates it from the create/update/complete/cancel sibling tools.

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: this is for reading the current status of an existing checkout by id, which implies polling after creation. It does not explicitly name alternatives or exclusion cases, so it falls 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?

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: it never consumes quota or charges by itself, locked sections are listed in `locked`, unavailable tiers return `unlock_required`, and part of the text is AI-generated via `disclosure`. No contradiction 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?

The description is dense but every clause earns its place: purpose, sections, auth requirement, tier gating, lock behavior, payment possibility, quota neutrality, and AI disclosure. It is front-loaded with the core purpose and avoids filler.

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

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

Given the output schema exists and annotations cover safety, the description is complete enough for correct invocation. It covers prerequisites, account verification, scope, tier unlock conditions, fallback responses, quota/charging semantics, and AI disclosure. An agent has what it needs to select and call 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 100%, so the baseline is 3. The description adds meaningful tier behavior: `basic`/`completo` only work when unlocked, otherwise `unlock_required` is returned, and it enriches the `tier` parameter meaning beyond the schema. It does not need to repeat the `id` format since the schema already documents it.

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 identifies the produced artifact: a viability report for an auction, with the exact sections included. Although phrased as a noun phrase, the meaning is unmistakable, and the `locked` distinction plus section list separates it from sibling auction tools like `subasta` or `analisis_subasta`.

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 gives concrete usage context: it requires a verified account and scope `informes:read`, and it explains how locked tiers behave, including the `unlock_required` fallback and optional payment link. It does not explicitly name sibling alternatives or state when to prefer this tool over them, but the conditions for use are clear.

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 mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable non-redundant behavior: authentication scope, plan requirement, and the specific error payload when access is insufficient. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence front-loads the data product, metrics, and filter dimensions; the second covers access requirements and the failure mode. Every clause contributes necessary information.

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

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

For a read-only report with an output schema, optional parameters, and annotation-covered safety, the description is largely complete: purpose, metrics, filters, auth, and lock behavior are all stated. Minor gaps are the absence of an explicit no-filter default behavior and lack of a named public alternative.

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 100% coverage with descriptions for both parameters, so the baseline is 3. The description conceptually mentions filtering by province and/or property type but adds no format, default, or combination rules beyond what the schema already provides.

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 that the tool provides market statistics for resolved auctions, specifically adjudication rate, real discount, and prices, segmented by province and/or property type. This clearly identifies the resource and the kind of data returned, though it does not explicitly differentiate it from the sibling `estadisticas_publicas`.

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 gives clear preconditions: an account with scope `informes:read` and a Pro plan, and it describes the `plan_required`/`locked` failure mode. However, it does not explicitly say when to choose this tool over `estadisticas_publicas` or other siblings, so the use-vs-alternative guidance 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations by specifying the required OAuth scope and the kind of account data exposed. There is no contradiction with the 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 one compact sentence that front-loads the data categories and appends the scope requirement with no redundancy. Every element 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?

For a parameterless, read-only account-info tool with an output schema present, the description adequately covers what data is returned, the authentication requirement, and the safety profile. No critical missing context is apparent.

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

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

The tool has zero parameters and the input schema is empty, so there is no parameter information for the description to add. Per the 0-parameter baseline, this receives 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 enumerates the exact contents of the account resource (plan, report quota, available functions, token scopes, usage limits, useful URLs), making the tool's purpose clear. It lacks an explicit verb like 'retrieves' or 'shows', but the resource and its attributes are specific enough to distinguish it from 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 provides a clear precondition: an account with the `cuenta:read` scope is required, which tells an agent when it can be invoked. However, there is no explicit when-to-use guidance or comparison with alternatives such as `planes` or `informe`; the usage context is mostly 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations: the request requires a specific OAuth scope (notas:read), and the PDF URL is only provided when the request is ready. This is valuable and does not contradict the 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 a single, front-loaded sentence with no wasted words. It conveys the operation, the deliverable, the timing condition, and the authentication requirement in a compact and readable way.

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 simple one-parameter read-only tool, an output schema, and strong annotations, the description covers the essential invocation context. It could add a note about how to obtain pedido_id or what happens when the request is not yet ready, but these are minor gaps rather than critical omissions.

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 does identify pedido_id as the identifier of a nota simple request, but it does not explain where the ID comes from, its format, or how to obtain it. Since there is only one required, self-descriptive parameter, this partial compensation is minimally adequate.

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 operation: obtaining the status of a nota simple request and the URL to view/download the PDF when ready. It is distinct from siblings like nota_simple_pedir (which creates a request) and notas_simples_listar (which lists requests) because it focuses on a single pedido's estado.

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 gives clear context: it is used to check the state of a nota simple request and obtain its PDF URL once available. It also states the account/scope requirement. It does not explicitly name alternative tools or give when-not-to-use guidance, but for a simple status lookup the context is sufficient.

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?

Beyond the annotations, the description reveals critical behavior: payment is never completed from this tool, the order is idempotent and returns `pedido_existente`, there is a 20-property daily limit, and billing only happens with a verified PDF. This is rich behavioral context that an agent needs to set expectations correctly.

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 dense but every sentence carries essential information: action, price and billing, prerequisites, return values, payment behavior, idempotency, and daily cap. It is front-loaded with the core purpose and contains 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?

With a single parameter, a rich output schema, and annotations covering idempotency and read/write behavior, the description adds all the missing operational context: prerequisites, payment flow, failure conditions, and limits. An agent has enough to invoke the tool correctly without further 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?

The schema already documents the only parameter, `id`, with its type, pattern, and meaning. The description adds context about the auction and CRU/IDUFIR requirements but does not add new parameter-level details 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?

The description opens with a specific verb and resource: 'Inicia el pedido de la nota simple registral de una subasta.' This clearly distinguishes the tool from sibling tools like nota_simple_estado or notas_simples_listar, which handle status or listing rather than initiating an order.

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 clearly states prerequisites: a verified account with scope `notas:write` and the subasta having CRU/IDUFIR, with `not_orderable` as the failure signal. It does not explicitly name alternatives by tool name, but it gives enough context for an agent to decide when this action is valid.

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 destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds useful behavioral context by stating that an authenticated account with the `notas:read` scope is required, and it clarifies that the operation concerns €20 nota simple requests. No contradiction 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?

The description is two short sentences with no redundancy. It front-loads the core purpose in the first sentence and adds the key access requirement in the second, making every word valuable.

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, read-only listing tool with an output schema available, the description plus annotations provide sufficient context. The account/scope requirement is stated, and because an output schema exists, there is no need to describe return values in prose.

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 is empty with 0 parameters, so parameter semantics are not a concern here. The baseline for a 0-parameter tool is 4, and the description appropriately does not attempt to document nonexistent parameters.

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 identifies the resource as 'Pedidos de nota simple registral' and indicates they come with their status, making it clear this tool lists nota simple requests. The title and tool name add the explicit verb 'listar' and scope 'mis notas simples'. It is distinguishable from sibling tools like nota_simple_pedir and nota_simple_estado, though it does not name them explicitly.

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 the tool is for viewing one's own nota simple requests and their status, and it states the authentication requirement (account with scope `notas:read`). However, it does not explicitly contrast with alternatives such as nota_simple_estado or nota_simple_pedir, so the when-to-use guidance is only implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds the practical behavioral detail that the tool is public and requires no account. It also states what kind of output to expect: plan prices and a feature comparison.

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

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

The description is two short sentences with no filler: the first enumerates the plans and the content delivered, and the second states the access requirement. Every word contributes useful 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 parameters and an output schema present, the description covers everything an agent needs: which plans are included, that prices and feature comparisons are provided, and that no account is required. There are no missing prerequisites or behavioral caveats.

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

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

The tool has zero parameters, so the schema fully covers the input surface. The description adds no parameter-specific details, but none are needed in this case.

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 identifies the resource (Subastech plans) and the content returned (prices and feature comparison), and it enumerates the specific plans: Radar gratuito, Starter, Pro, Team, Enterprise. It does not explicitly contrast with sibling informational tools like 'informe' or 'mercado', but the purpose is unambiguous.

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 phrase 'Pública, sin cuenta' clearly tells the agent that this tool can be invoked without authentication, which is useful usage guidance. It does not state exclusions or name alternatives, but for a simple parameterless informational tool this context is sufficient.

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 the operation read-only and idempotent, and the description adds meaningful behavioral detail: it uses the user's historical type/price/province data, requires a specific scope, and changes ranking logic depending on account plan. This goes beyond the annotations without contradicting them.

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 earning its place: the first explains what the tool provides, the second states the auth requirement, and the third clarifies plan-dependent ranking behavior. The description is front-loaded with the core purpose and contains 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?

With no parameters, a rich output schema present, and annotations covering safety hints, the description covers the remaining essentials: account requirement, scope, data sources, and plan-dependent behavior. Nothing critical is missing for an agent to decide to call it.

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

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

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because no parameter documentation burden exists.

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

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

The description clearly states the tool returns recommended auctions based on user history (type, price, provinces), and the 'para ti' block analogy makes the purpose immediately recognizable. This distinguishes it from search and similar-item sibling tools by emphasizing personalization from the user's own history.

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 gives clear usage context: an authenticated account is required, the `cuenta:read` scope is needed, and behavior depends on plan tier (Pro or higher uses scoring ranking; otherwise profile-based ranking by end date). It does not explicitly name alternative tools or state when not to use it, so it falls 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 provide read-only, idempotent, and non-destructive hints. The description adds useful behavioral context beyond annotations: it is public, requires no account, is capped at 15 results, and includes specific outcome fields like remate and discount. This is solid additional transparency for safe invocation.

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 compact sentence that front-loads the core purpose and packs in the optional filter, output highlights, authentication requirement, and result limit. There is no filler or 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 simple, read-only list tool with an output schema and complete annotations, the description covers the essential agent needs: what is returned, the optional province filter, result cap, and that no account is required. Nothing critical is missing 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?

The input schema already documents both parameters fully, including the maximum of 15 and the lowercase slug format for provincia. The description only restates 'opcionalmente por provincia' and 'Máximo 15', adding little semantic value beyond the schema's existing coverage.

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

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

The description clearly states that the tool returns the latest officially awarded BOE auctions, optionally filtered by province, along with the winning bid and discount. This is specific and distinguishes it from general search tools by emphasizing 'resultado oficial (adjudicadas)', though it does not explicitly name a sibling alternative.

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 gives clear context: use this for recent, officially adjudicated auctions, optionally narrowed by province. It also notes the tool is public and requires no account. However, it does not explicitly state when not to use it or which sibling tool to prefer for other 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?

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful extra context by stating that the tool is public and requires no account, and by describing the recommended follow-up workflow with `fetch`. This goes beyond what the annotations alone provide.

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 compact and front-loaded: it states the purpose, result shape, access model, and next step in two sentences. Every sentence contributes new information without padding or 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 simple one-parameter read-only tool with an output schema and safe annotations, the description covers purpose, return shape, authentication, and the follow-up call. It is nearly complete, though a brief note on when to prefer this over the sibling search tools would eliminate the remaining ambiguity.

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

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

Schema coverage is 100%, with the single `query` parameter already described as 'Búsqueda en lenguaje natural'. The description repeats this idea but does not add examples, formatting guidance, or constraints beyond what the schema already documents, so it stays at the baseline for fully covered schemas.

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 specifies a natural-language search over BOE judicial auctions and states the returned fields (`results` with `id`, `title`, `url`), so the core purpose is unambiguous. However, it does not explicitly differentiate this from sibling tools like `buscar_subastas` or `buscar_por_codigo`, which keeps it from a top score.

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 useful context: it is a public, account-free natural-language search, and it instructs the agent to use `fetch` with the `id` to read the full record. It does not explicitly state when to choose this tool over the other search-related siblings, so usage guidance is implied rather than explicit.

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?

Beyond the readOnly/idempotent annotations, the description discloses authentication requirements and plan-dependent sorting behavior. The `metodo: scoring`/`metodo: publico` parenthetical is slightly confusing because `metodo` is not present in the input schema, but the behavior itself is transparent.

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 dense sentences front-load the purpose and add only high-value operational details. There is 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?

The tool has an output schema and safe annotations, so the description covers the main context: purpose, criteria, auth, and ordering. However, it leaves `limite` undocumented and introduces `metodo` without a matching schema property, creating an incomplete picture for a caller.

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 `id` is described in the schema (50% coverage), so the description needed to compensate, but it never explains `limite` and instead references a `metodo` value that does not appear in the input schema. This does not add meaningful parameter guidance beyond the schema.

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

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

The description clearly states the tool returns auctions similar to a given one, with concrete similarity criteria (same property type, price band, proximity). It lacks an explicit verb but is unambiguous and distinguishable from generic search or recommendation tools.

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 use case is implied by 'a una dada' and the criteria, and the description adds explicit preconditions: account with scope informes:read and plan-dependent ordering. It does not name alternative tools or say when not to use it, but the context is clear.

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, destructiveHint=false. The description adds meaningful behavioral context beyond that: the tool is public and requires no account, some fields are gated behind a paid plan, and locked fields are returned as `locked` with an `upgradeUrl`. This is valuable for setting agent expectations about degraded responses and paywall behavior. The write-free, idempotent behavior is consistent with the annotations, and the description's claims do not contradict them.

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 compact but information-dense: two sentences cover input forms, returned fields, public access, paywall gating, and locked responses. It is front-loaded with the core purpose and input forms before diving into plan limitations. There is no filler or repetition of schema text.

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 presence of an output schema that can describe return values, the description covers the remaining contextual essentials: how to address the resource, what data is public, what requires a plan, and how locked fields behave. Input parameters are fully documented in the schema, so an agent has everything needed to invoke it correctly. The tool's complexity is moderate, and the description plus schema plus annotations form a complete picture.

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%: each parameter (id, url, boe_id) has its own schema description explaining format and semantics. The tool description adds the functional context of how the inputs relate to the resource: URL from app.subastech.com and BOE identifiers with the SUB- prefix. No parameters have enums and required is 0, which the description partly explains by saying the tool accepts 'por identificador, URL o identificador BOE,' implying any one is sufficient. The description does not add significant syntax beyond the schema except the BOE-ID-returns-all-lots note, so the baseline 3 is appropriate.

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

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

The description clearly states that this tool retrieves a public auction sheet from BOE by identifier, URL, or BOE ID, and lists the specific fields returned (address, values, dates, result, lots, summary). It is immediately distinguished from siblings like buscar_subastas or analisis_subasta because it is a single-record ficha by identifier rather than a search or analysis. The title 'Ficha de una subasta' reinforces the resource but the description adds the specific input forms and output coverage.

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 states the tool is public and requires no account, and it explicitly says which fields are available without login versus which require a plan. It also names the input formats (10-character ID, app.subastech.com URL, BOE identifier) and notes that BOE ID returns all lots. It does not explicitly name sibling alternatives or contrast with search tools, but for a lookup-by-identifier tool the usage context is clear enough. The clear public/no-account statement helps an agent decide when to use this tool over ones requiring auth.

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 indicate a mutating, idempotent, non-destructive operation. The description adds meaningful behavioral detail beyond that: content is replaced, price and status are recalculated, and certain session states are rejected. This is useful context that the annotations do not provide, though it does not cover failure modes or partial-update semantics.

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 dense sentences carry all the essential information: the action, the exact scope, the recalculation side effect, the forbidden states, and the required authentication header equivalent. No filler or redundant schema repetition.

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 nested schema and an output schema, the description covers the core behavior, the session-state limitations, and the platform identification requirement. It is complete enough for an agent to call the tool correctly in most cases, though it would benefit from explicitly routing to create_checkout when no session exists.

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 clarifies that checkout consists of line_items and buyer, and it explains the required meta['ucp-agent'] profile structure. However, it does not explain the id parameter or optional fields like payment, signals, and attribution, so the compensation is only partial.

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 a specific verb and resource: 'Reemplaza el contenido de una sesión de checkout UCP' and scopes exactly what is replaced (line_items y buyer). It also states the side effect of recalculating price and status, which clearly separates it from create, complete, cancel, and get checkout 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 description gives explicit exclusions: it does not support sessions in complete_in_progress or finished states, and it states the required meta['ucp-agent'] profile prerequisite. It does not explicitly name alternative tools like create_checkout or complete_checkout for when those states apply, so it stops just 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.