pandape_api

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

With no annotations, the description carries the burden of disclosing behavior. It reveals that the tool validates routes against the OpenAPI spec, acts as a fallback, and has a multipart/form-data nuance. It does not mention authentication, rate limits, or error handling, but for a generic API passthrough these are secondary. The disclosed behaviors are meaningful and not obvious from the schema 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?

Three sentences, each earning its place: the first states the core function, the second gives usage context and exclusions, the third warns about a critical parameter misuse. Information is front-loaded and the warning is an appropriate last note. 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?

Given the tool is a generic API caller with no output schema and no annotations, the description covers the essential usage aspects: what it does, when to use it, how to discover routes, and a key parameter pitfall. It does not enumerate all possible endpoints, but that would be impractical; the reference to the OpenAPI spec and sibling discovery tool suffices. Slightly more detail on auth/errors could push it to 5, but it is complete for its intended breadth.

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 60% (only body and ruta have explicit descriptions), so the description adds value by clarifying the 'form' vs 'body' distinction and giving an example ruta ('/v2/requests'). It does not explain 'metodo' or 'query', but their meanings are largely inferable from names and enum values. Overall, the description compensates for the schema's gaps without re-stating what is already clear.

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 it 'Llama cualquier endpoint de la API de Pandapé validando la ruta contra el spec OpenAPI' – a specific verb (calls), resource (any Pandapé API endpoint), and distinguishing scope (validates against OpenAPI). It also explicitly contrasts with named sibling tools, positioning itself as the catch-all fallback. This fully distinguishes it from the 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 explicit when-to-use guidance: 'Úsalo para lo que no cubren las tools con nombre' and lists example resource types. It also directs users to 'Descubre rutas con pandape_endpoints' for route discovery and warns about multipart/form-data requiring 'form' instead of 'body'. This gives clear decision-making context and avoids ambiguity with specialized siblings.

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