Adoteca — Adoção de Pets no Brasil

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

The description adds meaningful behavioral detail beyond the read-only annotation: it explains that if `url` comes back null, there is no link and the agent should read `note` and suggest removing a filter. It also warns 'Nunca escreva um link de catálogo à mão,' which prevents a common misuse.

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?

Four short, purposeful sentences with no filler. The core purpose is front-loaded, followed by usage context, error handling, and a critical constraint. Every sentence earns its place.

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 read-only link-building tool with full schema coverage and an output schema, the description covers what matters: when to use it, what the null-url behavior is, and a key anti-manual-link constraint. Nothing necessary for an agent to call it correctly seems 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?

The input schema covers 100% of the parameters, so the baseline is 3. The description only refers generally to 'os filtros pedidos' and does not add parameter-specific meaning, but that is acceptable because every parameter already has a detailed description in the schema.

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 uses a specific verb ('Monta') and resource ('link do catálogo') and clearly states the tool's core function: build a catalog link with requested filters and verify pets exist under those filters. It also distinguishes itself by mentioning the null-url case and warning against hand-writing links, which makes the tool's responsibility unambiguous.

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?

The description explicitly says to use this tool when the person wants to see the list on the site, which gives a clear triggering context. It does not explicitly name alternatives or exclusions, but given the sibling tools are mostly search/detail tools rather than link builders, the usage context is strong enough.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral constraints beyond annotations: the city must already be resolved, the tool returns aggregate stats only, and it does not return pets or NGO identities. It also references error behavior for ambiguous or pet-less cities, giving useful operational context.

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 efficient: the first sentence lists the returned metrics and the resolved-city precondition, and the second sentence gives the primary use case and key exclusions. Every clause earns its place with 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's low complexity, two parameters, full schema coverage, and presence of an output schema plus safety annotations, the description covers everything an agent needs to invoke it correctly. It states what the stats include, when to use the tool, what it deliberately omits, and the required input precondition.

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 schema already documents both the city and state parameters thoroughly, including the slug/name format and optional UF. The description reinforces that the city must already be resolved, but it adds little beyond what the parameter descriptions already provide.

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 exactly what the tool returns: catalog counts for one already-resolved city, including pets by species, size, and age, plus adoptions, NGO counts, and common breeds. It also distinguishes itself from siblings by explicitly stating what it does not do (return pets, resolve city names, list which NGOs), making its purpose unmistakable.

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?

The description gives an explicit use case: 'Use para quantos pets tem em X?' and clearly states exclusions: it does not return pets, does not resolve city names, and does not list which NGOs, pointing to the NGO search for that. However, it does not explicitly name the sibling tool for resolving city names or for obtaining pet lists, leaving a small inference gap.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral guidance beyond the schema by instructing the agent to read the pet's `status` before offering it and to check each `health_conditions` status before discussing health, which prevents misinterpretation of the data.

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 concise and well-ordered: first it states what the tool returns, then what input it accepts, and finally the critical reading instructions. Every sentence carries meaningful information with no 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?

For a single-parameter read-only tool with an output schema, annotations, and a clear workflow reference, the description covers all necessary aspects. It explains the input source, the content scope, and the important status-reading behavior, so an agent can invoke and interpret the tool 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%, so the schema already documents `pet_ref` as the short pet code or record identifier. The description adds marginal context by specifying that the code may come from a link or from the pet search results, but it does not substantially expand on the schema's 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?

The description clearly identifies the resource ('ficha completa de um pet') and the specific information it returns: health, care, coexistence, and how to contact the NGO. It also distinguishes itself from the search flow by stating that it accepts the short code from a link or the id returned by the pet search, making it easy to tell apart from search_pets and get_rescuer_details.

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?

The description gives clear context for when to use the tool: after obtaining a pet reference from a link or from the pet search, instead of searching again. It does not explicitly name alternative tools or state when not to use it, but the intended workflow is strongly implied.

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?

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description adds a concrete behavioral rule: for donations show donation_url or profile_url and never ask or forward a PIX key. This is useful safety context that structured annotations do not provide.

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 short sentences front-load the resource and its fields, then give input-format and donation-handling guidance. No filler or repetition of schema details.

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?

The single required parameter is fully documented, an output schema exists, and the description covers input provenance plus the donation display rule. There are no material gaps for an agent to call this simple lookup tool 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 schema already explains both accepted formats (short code without @ and Instagram handle without @). The description adds that the ref is returned by the NGO search, but this is a minor addition rather than a semantic clarification.

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 resource ('Ficha de uma ONG ou protetor') and the returned content (cities served, contacts, website, donation page), making it distinct from sibling search tools like search_rescuers. It provides a clear, specific purpose for an agent.

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?

It explains that the accepted rescuer_ref comes from the NGO search ('devolvidos pela busca de ONGs'), which tells the agent to use search_rescuers first. It does not explicitly name the sibling or state when not to use this tool, but the context is clear enough.

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 mark readOnly/openWorld/non-destructive, and the description adds substantial behavioral context beyond them: results reflect the catalog 'hoje' (today), are sorted by frequency, and the SRD note instructs the agent to offer mixed-breed instead of claiming no pets exist. This edge-case heuristic directly changes agent behavior and is exactly the kind of disclosure that helps.

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: purpose and ordering, when to use, and the SRD fallback heuristic. Core information is front-loaded and there is zero 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?

For a simple one-optional-parameter list tool, everything an agent needs to call it correctly is present: purpose, usage triggers, ordering, slug semantics for the next call, and the empty-result edge case. An output schema exists so return shape needs no prose, and annotations cover the safety profile.

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% — the `species` parameter already documents accepted values ('dog'/'cachorro' or 'cat'/'gato') and its null default. The description adds nothing about the parameter, but with high schema coverage the baseline of 3 applies and the schema adequately carries that burden.

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 names a specific resource (breeds with pets in the catalog), a clear operation (listing, per the title 'Listar raças'), and precise scoping: results are ordered most-common-first and include slugs for the `breed` parameter. None of the nine sibling tools cover breeds, so it is cleanly differentiated.

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?

It states explicit usage triggers: 'Use antes de filtrar por raça e quando perguntarem quais raças existem' (use before breed filtering and when asked which breeds exist). It does not name explicit alternatives or when-not-to-use, but no sibling tool overlaps with the breed resource, so exclusions are less critical.

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 disclose read-only and non-destructive behavior, so the description doesn't need to repeat that. It adds valuable behavioral context about accent/typo tolerance and the 'ambiguous' output flag, including how to respond when it occurs. No contradiction with 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?

Three concise sentences in Portuguese, front-loaded with the core conversion, followed by usage, ambiguity handling, and an alternative-tool pointer. 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 output schema exists to define the return structure and annotations cover the safety profile, the description covers the key decision points: what it does, when to use it, how to deal with ambiguity, and where to get city statistics instead. Nothing critical 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?

With 100% schema description coverage, the parameter meaning is already fully documented. The description only reinforces that city accepts misspellings and accents, which is a minor extension of the schema's 'como a pessoa escreveu'. It doesn't clarify the state parameter's disambiguation role beyond the schema.

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 a specific verb-resource pair: it converts a city name to the official catalog slug. It also frames this as a prerequisite for other searches, distinguishing it from siblings like search_pets and get_city_stats.

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?

It explicitly says 'Use antes das outras buscas quando a pessoa citar uma cidade', giving a clear when-to-use directive. It also routes city statistics away with 'Para os números da cidade, use as estatísticas', and the ambiguous-result rule advises the agent to ask or infer, never guess.

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?

Discloses response behavior beyond annotations: respond based on the 'summary', show the 'url', and tell the user if no guide exists (empty list). These instructions add practical execution detail not found in readOnly/openWorld hints.

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: two sentences cover what the tool does, when to use it, and how to handle responses. Every sentence adds value with no 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?

With a complete output schema, clear annotations, and a well-scoped description, all essential information is present. It even addresses edge-case behavior (empty list), making it fully contextual.

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% for the single 'query' parameter, and its description is thorough (free-text, examples, tolerates accents/typos). The tool description does not add parameter-specific semantics beyond this, so baseline 3 is appropriate.

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 the tool's purpose: accessing Adoteca guides on adoption, health, special care, and site usage. It distinguishes itself from pet-search tools by explicitly saying it's for questions that are not pet searches.

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 guidance on when to use: 'Use para dúvidas que não são busca de pets' (use for doubts that are not pet searches). This differentiates the tool from sibling search_pets and offers clear usage context.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral guidance beyond that: the catalog includes already-adopted pets, the agent must read `status` and only offer 'available', must show `adoption_url`, and must never invent pets. This materially changes how the tool should be used.

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?

Four focused sentences front-load the scope and purpose, then add essential operational cautions. Every sentence earns its place and there is no filler or repetition of schema content.

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 18-parameter search tool with an output schema and read-only/open-world annotations, the description is complete for correct invocation. It covers the main use case, the availability filter, the required URL field, and the anti-hallucination rule; the schema handles detailed parameter semantics.

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 the schema itself provides rich per-parameter guidance (e.g., city must be written out in full, breed accepts slug or Portuguese name, false for vaccinated is ignored). The tool description adds only a general filter list, not new parameter meaning, so the baseline of 3 applies.

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 names a specific verb and resource: 'Busca em TODO o catálogo de cães e gatos para adoção no Brasil', and lists concrete filters such as cidade, espécie, porte, idade, or nome. It also establishes this as the default adoption search, clearly separating it from sibling tools like search_rescuers and search_cities.

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?

It explicitly frames the tool as "a busca padrão de quem quer adotar", giving clear context for when to use it. It does not explicitly name alternatives or state when not to use it, but the sibling list and filter structure make the intended usage sufficiently clear.

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?

Beyond annotations, the description warns that ads may be old ('Anúncios podem ser antigos: não afirme que a ONG está ativa'), the registry is incomplete ('Não é registro completo'), and it cannot answer capacity ('nunca afirme que tem vaga'). These are behavioral caveats that align with openWorldHint and add actionable constraints.

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 short, purposeful sentences: trigger, output shape, then two safety caveats. The most decision-relevant phrase is front-loaded and no sentence is wasted.

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 an output schema and detailed input schema, the description supplies the remaining operational context: result is a list with links, not a complete register, and no capacity/activity claims should be made. Nothing needed 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 each parameter has its own detailed description (city, page, limit, state). The tool description adds no per-parameter semantics beyond the catalog/link scope, so it earns the baseline 3 rather than higher.

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 opens with the exact user-intent trigger ('QUAIS ONGs ou protetores existem em uma cidade') and defines the result: NGOs/protetores that have pets in the catalog, with each link. This is a concrete verb+resource statement that separates the list search from detail tools like get_rescuer_details.

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?

It explicitly says 'Use quando perguntarem QUAIS ONGs ou protetores existem em uma cidade', giving a clear activation condition. It stops short of naming sibling alternatives or saying when not to call it, but it does block misuse by warning not to claim active status or availability.

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 mark the tool as read-only and open-world, and the description adds meaningful behavioral disclosure: results may be empty, 'total' reflects only this list, and there is no page 2. It also instructs the agent to show adoption_url and not fabricate pets, which is valuable runtime guidance beyond the structured 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 description is compact and front-loaded with the core purpose, then adds only high-value operational details: when to use, fallback behavior, output requirements, and pagination absence. Every sentence earns its place with no redundancy or 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?

For a simple two-parameter read-only tool with a full input schema and an output schema, the description covers all essential calling context: search scope, trigger condition, empty-result handling, required display field, and pagination behavior. Nothing necessary for correct invocation 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%, so the schema already fully documents pet_ref and limit, including the max of 24 and absence of pagination. The description adds context about search criteria (same species and city) and output behavior, but not new parameter-level meaning, so the baseline of 3 is appropriate.

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 names a specific action and resource: finding pets similar to one specific pet, restricted to the same species and city. It explicitly distinguishes itself from the general catalog search ('não é a busca geral do catálogo') and from the sibling tool search_pets, so an agent can select it correctly.

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?

The description gives a clear trigger condition: 'Use quando o pet desejado já não estiver disponível.' It also names the alternative (searchPets) and explains what to do when the result is empty: use searchPets and never invent pets. This is explicit when-to-use guidance with a fallback path.

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