LQN Broker

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds that it explains two models and, if a monto is provided, indicates whether the credit can be referred—useful conditional output context, though no auth/rate/edge-case details.

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

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

Two sentences, front-loaded with the core explanation and followed by usage guidance. No filler or repetition; appropriately sized for the tool's complexity.

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

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

The tool is informational with two optional params and no output schema. The description sufficiently covers what it returns (the two LQN working models and referral eligibility when monto is given) and when to call it, though it could mention rol omission behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a specific use for monto_credito (indicates referral eligibility) beyond the schema's 'estimar la ganancia', but rol is left to the schema enum descriptions.

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

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

States a specific verb (Explica) and resource (modelos de trabajo con LQN en crédito hipotecario), detailing the two models. It implicitly separates this informational tool from action siblings like radicar_con_lqn, but does not name alternatives.

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

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

Gives explicit trigger phrases: 'Úsalo cuando pregunten cómo trabajar con LQN, cómo se paga o si un agente inmobiliario puede referir clientes.' No when-not or alternative tool routing, so it is clear but not exhaustive.

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/non-destructive, so the safety profile is covered. The description adds value beyond them: the output artifact (Ficha HipoCredit with a WhatsApp button) and product rules that shape the result (LTV cap, monetary range, term cap). It does not mention authorization or rate-limit behavior, which keeps it out of 5 territory.

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

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

Front-loaded with purpose, product and limits, then the usage condition. It is a single long sentence-pack, but each clause carries distinct information (product, limits, outputs, when/when-not). Minor density cost keeps it from 5.

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

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

With 16 parameters and no output schema, the description compensates by describing what the agent gets back (rate range, cuota, plazo, condiciones, Ficha with WhatsApp button) and the eligibility rules. It omits nothing critical, though codeudor/score/campaign-style inputs are left entirely to the schema.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description goes further by tying business logic to parameters: the 40%-of-value cap maps to valor_inmueble, the $10 M–$300 M band maps to monto_solicitado, and 'plazo hasta 84 meses' clarifies plazo_meses. That is real added meaning rather than restatement.

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

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

States a specific verb+resource ('Perfila un crédito de libre inversión con garantía de vivienda') and names the exact product (HipoCredit, crédito propio de LQN), with concrete scope (40% del valor, $10 M–$300 M, hasta 84 meses). An agent can distinguish it from radicar_con_lqn (submission) and simular_cuota (single-quote simulation) without opening any schema.

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

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

Gives explicit eligibility context ('cuando el cliente ya tiene casa o apartamento propio y necesita liquidez') and a clear exclusion ('no aplica para comprar vivienda'). It stops short of naming the sibling to use instead for home purchase, so it is strong but not fully routing.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: the exact decision outputs (three-state semáforo, allied banks passed with reasons for rejections, affordability metrics) and the side-effect-free presentation of a 'Ficha LQN' with a WhatsApp filing button. It stops short of stating determinism or sensitivity to missing optional inputs.

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

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

Three sentences, front-loaded with purpose and scope, followed by a dense output enumeration and a usage trigger. The middle sentence is a long comma list but each item is a distinct deliverable, so little is wasted; the WhatsApp button detail is arguably the least load-bearing clause.

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 20 parameters, no output schema and read-only annotations, the description does the heavy lifting on returns by enumerating every headline output, which is exactly what an agent needs to decide to call it. It could still say more about behavior when required fields are missing or how the three semáforo states are decided, but nothing essential is absent.

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 95% across 20 parameters, so the schema itself carries nearly all parameter meaning (enums for rol, tipo_ingreso, tipo_vivienda, estado_inmueble; defaults for plazo_anios; derived tipo_vivienda). The description adds no parameter-level detail beyond the output field list, so the baseline of 3 is appropriate.

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

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

States a specific verb (perfilar) plus a tightly scoped resource (negocio de crédito hipotecario en Colombia con criterios LQN), and enumerates the concrete artifacts produced (semáforo, bancos aliados, monto, cuota, % cuota/ingreso, Mi Casa Ya, documentos). The 'crédito hipotecario' scope inherently separates it from the sibling perfilar_libre_inversion and from simular_cuota.

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

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

The closing sentence gives an explicit trigger: use it when a broker or asesor wants to know whether their client qualifies for a vivienda loan. It does not name when NOT to use it or point to alternatives such as simular_cuota (for a single payment calculation) or radicar_con_lqn (for actually filing), so routing is clear but not complete.

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/non-destructive/openWorld=false, yet the description adds real behavioral context beyond them: it does NOT create a radicación, does NOT verify role, and LQN performs identity/linking/authorization validation. This tells the agent the tool is a preparatory handoff, not an action. It omits what the produced handoff looks like or any limits, so not a 5.

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, zero filler, and front-loaded: purpose first, then the boundary/validation note, then the usage trigger. Efficient and well-ordered with no restated title.

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 handoff-preparation tool with 0 required params and no output schema, the description conveys what it does, what it deliberately does not do, and who validates downstream. Return-value detail is not spelled out (what the WhatsApp handoff payload contains), a minor gap given no output schema 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 100%, so the enum and each optional parameter are already documented in the schema. The description paraphrases the three role values (broker vinculado, broker nuevo, agentii) without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (prepara el handoff) and resource (handoff por WhatsApp para radicar con LQN), covering the three modalidades. This is clearly distinct from siblings like simular_cuota, perfilar_negocio or como_ganar_con_lqn, so an agent can route to it without opening the schema.

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

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

Gives explicit trigger utterances: 'Úsalo cuando digan que quieren radicar, vincularse, referir o hablar con LQN.' It also sets a boundary by clarifying it does not create the filing. However, it names no sibling alternative for cases where the user wants something else (e.g., quoting vs filing), so it stops short of full when/when-not/alternatives routing.

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

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

Annotations already establish the safe read-only, idempotent, closed-world profile, so the bar is lower; the description still adds real value by disclosing the assumed reference rate (12,5% E.A.) and that the result is 'orientativa'. It does not say how it behaves if neither monto nor ingreso is supplied, but the core behavioral context 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 tight sentences: the first front-loads the calculation, rate assumption and both modes; the second supplies usage examples. No filler, and the most decision-relevant content leads.

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

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

With no output schema, four fully documented parameters, and complete annotations, the description supplies everything an agent needs: what is computed, the rate basis, the indicative nature, and which input drives which mode. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so every parameter (including the rol enum) is already documented in the schema. The description explains the two input modes and their relationship, but this largely restates what the schema descriptions already convey, so the baseline 3 applies.

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

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

States a precise verb+resource ('Calcula la cuota mensual orientativa de un crédito hipotecario en Colombia') and even covers the two operating modes (payment from monto+plazo, or max amount from ingreso). The purpose is unmistakable, though it never explicitly names or contrasts itself with the siblings like perfilar_negocio or radicar_con_lqn.

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

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

Gives concrete when-to-use guidance via sample queries ('¿cuánto paga por 200 millones a 20 años?', '¿cuánto le prestan ganando 5 millones?'), which maps user phrasings to the tool. It stops short of stating when not to use it or pointing to an alternative sibling for other mortgage scenarios.

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