Juntamos: organizar grupos

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

Annotations declare this as a non-read-only, non-idempotent mutation, and the description adds useful beyond-annotation context: it returns settlement payments, the total and the group link, and requires the admin link/token. It misses one relevant trait the idempotentHint=false implies — that repeated calls would add duplicate expenses — so it isn't fully transparent about re-invocation risk.

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

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

Purpose, examples, returns and limits are front-loaded and each carries information. The only waste is the verbatim bilingual duplication (Spanish then English), which roughly doubles the length without adding content for a given reader.

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 present, the description carries the return contract (who owes whom, payments to settle, total, group link) and the key preconditions (admin token, names present in group), so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating a real business rule the schema omits ('names must be in the group'), and it clarifies the id_admin linkage, though the 'empty entre_quienes means everyone' note merely restates the schema description.

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 concrete verb+resource ('adds an expense to a shared expenses group') and explicitly ties it to the upstream sibling that creates the group (crear_gastos), which is the closest relative among the siblings. An agent can tell this is the post-creation expense-adding step, not group creation or a poll/date tool.

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 two concrete utterance-style examples ('Ana pagó 60 € de la cena entre todos') that make the trigger conditions unmistakable, plus limits on preconditions. It does not, however, state when to use this versus ver_resultados or crear_gastos, so it stops short of explicit alternative routing.

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

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

Annotations only declare the generic safety profile (not read-only, not destructive, not idempotent). The description goes well beyond them: it discloses that each participant sees only their own assignee, that the full result is never returned, the exact return artefacts (private link per person, public group page, organiser admin link), and operational limits (3–100 distinct participants, no emails, deletion after 90 days).

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 core purpose is front-loaded in the first sentence, followed by examples, return values and limits in a logical order. It is somewhat long because every sentence is duplicated in Spanish and English, which is redundant padding for a reader who understands either language.

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

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

There is no output schema, and the description compensates fully by enumerating the three returned links and warning that the full draw result is never returned. Combined with the participant limits, exclusion behaviour and retention policy, an agent has everything needed to call and explain the tool.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including the participant count bounds and the exclusion pair format. The description restates the 3–100 participant limit and the exclusion concept but adds no syntax or format detail beyond what the schema 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?

States a specific verb and resource: it performs the Secret Santa draw on the server and generates one private link per participant. It is immediately distinguishable from siblings like crear_encuesta, crear_eleccion_fecha or anadir_gasto, which handle polls, dates and expenses rather than a draw.

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 three concrete invocation examples ('organiza un amigo invisible con Ana, Luis, Marta y Pablo, presupuesto 20 €', the office variant with exclusions, the family variant), which gives clear context for when to use it. It does not, however, name an alternative tool or state when not to use it.

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

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

Annotations already declare the non-read-only, non-destructive, non-idempotent profile, so the bar is lower. The description goes beyond them by disclosing hard limits (2-31 days, YYYY-MM-DD, no past dates, up to 100 people) and the return payload (participant link plus admin link). It does not warn that re-invoking creates a duplicate page, which matters given idempotentHint=false.

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

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

Front-loaded with purpose, then examples, then returns, then limits — a sensible order, and every section carries information. The cost is the full bilingual duplication, which roughly doubles length, though it is a reasonable choice for a Spanish-language tool.

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 low-complexity 3-parameter creation tool with no output schema, the definition covers purpose, triggering examples, return values, and validity constraints. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions and an enum for idioma. The description adds value on top by restating the allowed count (2-31) and format (YYYY-MM-DD) and the 100-person cap, giving the agent constraint context the schema only partially encodes.

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 ('Crea una página para que un grupo elija fecha') and spells out the mechanism (each person marks yes/needed/no, best date highlighted). This is clearly distinguishable from siblings like crear_encuesta or crear_amigo_invisible 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?

It provides three concrete example prompts ('Christmas dinner', 'November weekend', 'alumni reunion') that directly tell the agent when this tool applies, which is strong when-to-use context. It stops short of naming when NOT to use it or pointing to the sibling survey/expense tools as alternatives.

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

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

Annotations already cover the safety profile (write, not idempotent, not destructive, closed-world). The description adds real context beyond them: what the tool produces (a voting link to share and an admin link to close/view results), the live-results behavior, and hard limits (2-30 options, 100 voters, closing must be future). It does not mention permissions/ownership or what happens to an expired poll.

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 core purpose is front-loaded, then examples, returns, and limits in a tight sequence; every block carries information. The cost is that the entire text is duplicated verbatim in Spanish and English, which roughly doubles length for a bilingual audience without adding new semantics.

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

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

With no output schema, the description correctly takes on the return-value burden by naming both links produced, and it supplies the operational limits an agent needs to avoid failing calls. Remaining gaps (permissions, post-expiry behavior, whether a poll can be edited) are minor for a create-only tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: 'el cierre debe ser futuro' constrains the cierre timestamp, and the 2-30 option / 100-voter limits give context for opciones and the overall capacity. It restates the option count already encoded as minItems/maxItems, which is the only redundancy.

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

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

States a specific verb and resource ('Crea una encuesta o votación con opciones de texto para compartir con un grupo') plus its key modes (single/multiple, live results, optional close). It does not, however, draw a line against the sibling crear_eleccion_fecha, and its own example 'crea una encuesta de qué día hacemos la reunión' overlaps with that tool's territory.

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?

Three concrete example utterances ('haz una votación para elegir restaurante...', 'qué día hacemos la reunión', 'varias respuestas para elegir actividades') give an agent a clear picture of when to reach for this tool. There is no explicit when-not guidance or named alternative, so the boundary against crear_eleccion_fecha remains for the agent to infer.

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 only declare the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real operational context beyond them: two distinct return links with different permissions, the constraint chain 2-100 distinct participant names, and euro-denominated amounts. It never warns that the non-idempotent create will spawn a duplicate group on a repeated call, which is the one behavior an agent would most benefit from knowing.

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

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

Purpose is front-loaded and the sectioning (use cases, returns, limits) is easy to scan. However, the description is given twice, Spanish then English, roughly doubling its length with no added information for an agent that reads either language.

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

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

With no output schema, the description must carry the return contract, and it does: the group link (everyone can add expenses) and the admin link (required for anadir_gasto and ver_resultados). Combined with the participant and currency limits, an agent has what it needs to call the tool correctly, though duplicate-call behavior and post-creation workflow remain implicit.

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

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

Schema description coverage is 100%, so the schema already documents titulo, participantes (2-100, distinct names) and the es/en idioma enum. The description's limits largely repeat the schema; only "importes en euros" adds information the schema does not encode. Baseline 3 is appropriate.

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

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

States a specific verb+resource (creates a shared-expense group) plus its domain (trip, flat, dinner) and the core mechanic (who paid what, minimal-settlement calculation). It also names the downstream siblings (anadir_gasto, ver_resultados), so an agent can place it in the workflow without inspecting other schemas.

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?

Concrete invocation examples ("create an expense group for the trip with Ann, Luke and Mary", "split the holiday cottage costs between 6") make the intended context unmistakable, and it explains that the returned admin link feeds anadir_gasto and ver_resultados. It stops short of stating when NOT to use it versus siblings like crear_encuesta or crear_lista_quien_trae.

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 declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description only needs to add context — and it does: it discloses the two return artifacts (sign-up link and admin link), the 1–100 item limit, and that anyone in the group can append items. It does not explain what happens after the list is consumed or how the admin link is protected.

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?

Each language block is front-loaded and tight, but the entire description is duplicated verbatim in Spanish and English, which doubles the length for identical content. The duplication has some justification for a bilingual tool, but it is still redundant text that must be read through.

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

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

With no output schema, the description compensates by naming the two returned links, and it covers limits and the core semantics of a 4-parameter creation tool. What remains thin is the multi-user/lifecycle behaviour (what group membership means, whether the admin link shares control), which matters for a collaborative sign-up list.

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 titulo, elementos, fecha and idioma are already documented in the schema, including format examples. The description's '1 a 100 cosas' and item examples merely restate the schema's minItems/maxItems, adding no format or syntax detail beyond it — the baseline 3.

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

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

States a specific verb and resource ('Crea una lista de cosas que hacen falta') plus the mechanism that makes it distinct: each person signs up for what they will bring, without duplicates. That mechanism cleanly separates it from siblings like crear_encuesta, crear_eleccion_fecha and crear_amigo_invisible.

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 three concrete user-utterance trigger examples ('haz una lista de quién trae qué para la barbacoa del sábado', etc.), which give strong when-to-use signal. It stops short of an explicit when-not or a named alternative sibling, so it is clear context without 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, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely new behavioral facts: an admin link/token credential is required, and the tool deliberately never reveals Secret Santa pairings. It stops short of describing pagination or size limits, but for a read-only summary that is acceptable.

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 what the tool shows, then use cases, then return value, then limits — a sensible ordering. The content is duplicated verbatim in Spanish and English, which roughly doubles the length, but each language block is individually tight and waste-free.

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

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

There is no output schema, and the description compensates by stating the return content (a summary of results plus the event link). With the single required parameter documented in the schema and the auth/privacy limits spelled out, an agent has everything needed to call this 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?

Only one parameter, and schema coverage is 100% (the schema itself describes id_admin as "Enlace o token de administración"). The description still adds useful framing by calling it a hard requirement and an administrative credential, which clarifies the privilege level the caller needs.

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 ("Muestra el estado de un evento de Juntamos") and then enumerates the exact result domains covered: poll votes, best date, who brings what, who owes whom, Secret Santa opens. This clearly separates it from the sibling tools, which are all creation tools (crear_encuesta, anadir_gasto, etc.).

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 concrete triggering questions ("¿cómo va la votación del restaurante?", "¿quién debe a quién en el viaje?") that map directly onto user intent. It does not, however, state any when-not conditions or name an alternative tool, though the sibling set makes the read-vs-create split self-evident.

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