Reinventa (qué tareas de tu trabajo hará la IA)

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

Annotations already declare readOnly/idempotent/closed-world, yet the description still adds substantial context: exact return payload shape, the presence of a Spanish prose answer mirrored in 'structuredContent' beginning with 'url', a mandatory linking obligation, and the disclaimer/citation constraints ('no asesoramiento laboral', 'Cita «Fuente: Reinventa»'). This is behavior an agent cannot infer from the 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?

Front-loaded with purpose and outcome, then usage, then response/format rules. Every clause carries information, but the final disclaimer and citation sentences are dense and could be split or trimmed without losing guidance.

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 describing the returned fields, the structuredContent envelope, and the fallback payload. Combined with the sibling routing and constraint notes, an agent has everything needed to call and to use the result correctly.

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

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

Schema coverage is 100% and the single parameter is documented, so baseline is met; the description nonetheless adds real value by showing that 'texto' accepts free natural-language phrasings ('contable', 'llevo la contabilidad de una pyme', 'ingeniera de software'), which tells the agent not to normalize input to a canonical job title.

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 una profesión ... entre los 50 perfiles con tablas de Reinventa') and fully spells out both outcomes: on a hit it returns the profile fields, on a miss it returns nearest professions, detected sector and next steps. It is clearly distinguishable from evaluar_tareas, which it explicitly routes to.

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?

Explicit ordering rule: 'Úsala primero cuando no sepas si la profesión está en las tablas'. It also gives the negative case and the follow-up path (describir las tareas y usar evaluar_tareas, o la evaluación completa donde la IA propone tareas), so the agent knows both when to call it and what to do after.

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 only cover the safety profile (readOnly, idempotent, non-destructive, closed-world); the description goes well beyond them. It discloses the return payload in detail, the ordering weighting rule (first three tasks weigh 1.5), the fallback for names not in the tables (aumentables, 55/100), the structuredContent contract starting with 'url', and the required disclaimer and citation. It even names the prohibitions (no job-change advice, no naming companies or people), which an agent could not infer from the 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?

The core purpose is front-loaded in the first clause, and every subsequent sentence covers a distinct requirement (output shape, weighting, fallback rule, data-gathering policy, disclaimer, citation). It is dense and occasionally repeats what the schema already says, and the prose runs as one long block without structural breaks, which costs it a point.

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 7-parameter tool with a nested task array and no output schema, the description supplies everything the agent needs: the full return shape (index, tier thresholds, category breakdown, task map, first three weeks of the plan, links), the weighting behavior, the fallback scoring, and the presentation/citation obligations. Nothing essential to calling or reporting the result 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% and each parameter is individually documented, so the schema already carries the semantics. The description restates the input set and the task-ordering and augmentable-task rules, but those rules already appear in the schema text for 'tareas' and 'nombre'. Baseline 3 is appropriate — it adds emphasis but little new meaning.

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 — 'Calcula el índice de resiliencia (0–100)' — and pins it to the same engine as the reinventa.es evaluation, so the agent knows exactly what is produced. It also names the sibling it depends on for task ids ('ver tareas_de_una_profesion'), which separates it from the lookup and guide 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?

Gives clear operating context: gather missing data from the person rather than inventing it, and explicitly do not ask for name, email or company. It also routes to tareas_de_una_profesion for ids. However, it never states when to prefer a sibling instead — e.g. when guia_de_profesion or explicar_metodo suffices without a full evaluation — so the alternative-selection guidance is incomplete.

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 this is a safe, idempotent, closed-world read; the description goes far beyond by explaining the response shape (Spanish text plus «structuredContent» beginning with «url»), the required citation, and hard behavioral limits — do not recommend quitting a job, do not identify companies or people, this is orientative and not labor advice.

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 content is front-loaded and almost every clause carries information, but it is delivered as one dense, minimally punctuated block where scoring weights, output contract, and safety constraints are interleaved. Splitting the response format and the disclaimers into separate sentences would make it far easier to act on.

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

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

No output schema exists, and the description fully compensates by specifying the return contract (ready-to-send Spanish text plus structuredContent keyed by «url») and how to use the URL. For a single optional-enum parameter tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the enum is already documented, but the description adds meaning by mapping the sections to actual method content (categories, starting scores, weights, AI, limits) and stating that «apartado» narrows the response to one part rather than changing the calculation.

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 — explains Reinventa's public index method as implemented in code — and enumerates the exact content (categories, starting scores, weights, tiers, AI role, limits). This clearly separates it from the sibling tools, which search professions or evaluate tasks rather than explain the methodology.

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 operational guidance: use «apartado» to restrict the answer to one section, link the returned «url» in the reply, and cite «Fuente: Reinventa (reinventa.es)». It never names the sibling tools or states when a caller should prefer evaluar_tareas or guia_de_profesion instead, so usage is well-contextualized but not fully disambiguated.

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?

Adds substantial behavior beyond the readOnly/idempotent/closed-world annotations: the response carries both a Spanish human-ready text and identical data in «structuredContent» beginning with «url», the no-guide fallback returns a message plus the list of guides, and the tool is explicitly framed as orientative, not labour advice, with prohibitions on recommending quitting a job or naming companies/people. That is real behavioral context an agent cannot get from 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 return-value description is front-loaded and tight, but the ~50-item profession list consumes most of the text and is costly in tokens. It does real work as an implicit enum, yet a more compact or referenced form would have been better structured.

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 fully carries the return-shape burden (text plus structuredContent with url), describes the not-found path, the citation/attribution requirement, and the safety boundaries. Nothing essential for correct invocation is missing for a single-parameter read 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 coverage is 100% and documents the single «profesion» parameter with an example, so the baseline would be 3. The description goes further by restating the name-or-slug lookup, giving the slug example «analista-financiero», and effectively supplying an implicit enum of ~50 valid profession names that the schema lacks.

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 and resource («Devuelve la guía … de reinventa.es») and enumerates exactly what the guide contains: introduction, per-task category/score/horizon/explanation/action, weekly plan and link. It is very clear what the tool delivers, but it never distinguishes itself from the sibling tareas_de_una_profesion, which an agent could plausibly reach for instead.

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

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

Explains how to look up («por nombre o por slug»), what happens when no guide exists (says so and lists available ones), and how to present the result (link the url, cite «Fuente: Reinventa»). It gives clear operational context but offers no explicit when-to-use/when-not guidance relative to buscar_profesion, evaluar_tareas or tareas_de_una_profesion.

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, and the description adds genuinely new behavior: the degraded result when the profession is unknown (sector + generic tasks, and it says so), the dual output shape (Spanish prose plus structuredContent starting with «url»), and the requirement to cite the source and avoid job advice. These are operational details an agent cannot infer from structured fields.

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

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

Front-loaded with what is returned, then usage, fallback, output contract and disclaimers; nearly every clause carries information. It is delivered as one dense run-on block without paragraph breaks, which makes the source-citation and disclaimer rules easy to skim past.

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 2-parameter read-only lookup with no output schema, the description covers what is returned, the fallback case, the output contract (url in structuredContent), and the citation/disclaimer obligations. Nothing an agent needs in order to call it and report the result correctly appears to be 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 the baseline is 3; the description adds value beyond it by explaining that passing «sector» appends that sector's 3 tasks and that «id» is the handle used downstream. It does not spell out the profession-name matching/normalization behavior (accents, feminine forms), which the schema hints at only via examples.

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?

Opens with a specific verb+resource ("Devuelve las tareas típicas de una profesión") and enumerates exactly what each task contains (id, categoría, puntuación 0-100, horizonte, razón, recomendación). It also positions itself against the sibling evaluar_tareas by saying its ids are the ones that get passed there, so an agent can tell it apart 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?

States the two concrete uses: showing a profession's task map and selecting tasks by id to feed evaluar_tareas, which routes the agent to the correct sibling for evaluation. It also documents the fallback path when the profession isn't in the tables. It never says explicitly when NOT to use it (e.g. vs buscar_profesion or guia_de_profesion), so it stops short of a 5.

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