buscar-ofertas

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

No annotations exist, so the description carries the full load and does most of it: it discloses session-dependent result breadth (~30 most recent unauthenticated), that filters default from the master profile, and that results carry an applied/already-applied indicator. Pagination behavior and result shape are left unstated, which keeps it short of 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 dense sentences ordered by importance: what/where, then session behavior, then default-filter semantics. Every clause carries information an agent needs and 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?

Given 11 optional parameters, no annotations and no output schema, the description covers the risky parts well: auth state changes results, defaults are inherited from the master profile, and results flag existing applications. It stops short of describing what a returned offer record looks like or how pagination interacts with the ~30-item unauthenticated cap.

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 73% and the description mainly restates what the schema already says about remoto and sin_visa_eeuu (defaults from preferencias.modalidad and datos_personales.pais). It clarifies the effective filtering consequence of those defaults, which is mild added value, but says nothing about orden, pagina, por_pagina, tipo or con_salario beyond their schema entries.

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 ofertas") plus the exact source and scope: Work at a Startup, Y Combinator companies, mostly English and US-based. That scope immediately separates it from detalle-de-oferta (needs an id) and mis-postulaciones (already-applied list), so an agent can pick 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?

Explains the two operating modes clearly: with a session it searches all offers with filters and flags prior applications; without a session it only returns the ~30 most recent. It does not name a sibling to use instead (e.g. detalle-de-oferta for a single posting, evaluar-encaje for fit scoring), so routing is implicit rather than explicit.

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