olist_contas_pagar_pesquisa

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

No annotations are provided, so the description carries the full behavioral-disclosure burden, yet it discloses nothing about pagination, return shape, filter behavior, or response semantics. It only restates the search action and points to an external docs URL; the word 'Pesquisar' implies a read operation but no observable behavior is described.

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 description is compact and front-loaded: purpose/version, endpoint, and docs URL are given in three short clauses. Minor redundancy exists ('API 2.0' vs 'API V2', the resource appearing in both the purpose and endpoint), but overall every clause contributes a distinct, useful piece of information.

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 an 8-parameter search tool with no output schema and no annotations, the description is under-specified. It tells the agent what endpoint to call and where to find docs, but not what the response looks like, how pagination works, or what occurs when no filters are supplied—important gaps given all parameters are optional.

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 even without parameter details in the description. The description itself adds no parameter semantics—it mentions only the endpoint and docs—while the schema already documents all 8 parameters, including the dd/mm/yyyy date formats and the 'pagina' page-number field.

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 the tool's core function—'Pesquisar Contas a Pagar' (Search Accounts Payable)—and adds the API V2 endpoint string and a documentation URL. However, the phrase 'Pesquisar Contas a Pagar' is essentially a restatement of the tool name (contas_pagar_pesquisa), and it does not differentiate this search from sibling tools such as olist_contas_receber_pesquisa or clarify what the search returns.

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?

No when-to-use guidance is provided. The description never mentions when to choose this search over related siblings (e.g., olist_conta_pagar_obter for a specific payable, olist_contas_receber_pesquisa for accounts receivable), and no prerequisites, exclusions, or typical scenarios are given.

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