search_sonhos

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

Não há annotations, então a descrição carrega essa responsabilidade. Ela informa que a busca retorna sonhos com slug + resumo, o que é bom, mas não detalha comportamento como limites de resultados, ordenação, o que acontece sem correspondências, ou se a busca é parcial/exata.

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?

Três frases curtas e diretas, com a ação principal na primeira sentença e exemplos práticos na segunda. Não há conteúdo redundante ou desnecessário.

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?

Para uma ferramenta simples com apenas um parâmetro obrigatório e sem output schema, a descrição cobre o essencial: o que busca, como buscar e o formato do retorno (slug + resumo). Faltam apenas detalhes menores como quantidade máxima de resultados, mas nada crítico para o uso.

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?

O schema já documenta 100% do parâmetro q, mas a descrição agrega valor ao dar exemplos concretos ('agua', 'cabelo', 'bebê') e ao indicar que são termos em português. Isso ajuda o agente a entender o formato esperado do input.

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?

A descrição usa verbo específico ('Busca') e recurso claro ('sonhos no livro dos sonhos') com o critério de busca ('por keyword'). Além disso, diferencia-se implicitamente do sibling get_sonho, que provavelmente recupera um sonho específico, enquanto este busca por termo livre.

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?

O uso é inferido pela descrição: deve ser usado para localizar sonhos por palavra-chave. Porém, não há orientação explícita sobre quando usar esta ferramenta em vez de get_sonho ou das demais alternativas, nem exclusões ou condições.

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