Petnecto

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful scope context (it explains listing sources and removal behavior) but discloses no further behavioral traits such as return format or granularity.

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?

A single short sentence that front-loads the first topic (where pets are listed). It is appropriately sized for a zero-arg informational tool, though the run-on list style and dangling 'what it keeps' cost a bit of crispness.

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 parameterless read-only tool with no output schema, the description covers the informational domains an agent would query. It stops short of indicating how the returned documentation is organized, but nothing essential to 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?

The tool takes zero parameters, so there is nothing for the description to document and the baseline is 4. Schema coverage is 100% with an empty properties object, matching the description's parameter-free nature.

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 enumerates the concrete topics the tool surfaces: pet listing locations and counts, listing provenance, service ownership, retention, and how rescues change or remove listings. That is a clear informational/meta purpose, though the phrasing ('what it keeps') is slightly vague and it never states plainly that it returns service documentation.

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 sentence tells the agent when to call this versus the sibling tools (find_pets, get_rescue, etc.). Usage is only inferable from the topic list; there is no explicit trigger, prerequisite, or exclusion.

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?

With readOnly/idempotent annotations already covering safety, the description adds substantial behavioural context: coverage is limited to listed regions, found pets are never adoptable, an uncovered place yields nearest pets 'marked not nearby', and an empty answer explains the inventory. These are operationally important facts absent from 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?

Front-loaded with the resource and scope, then filters, then return shape; nearly every clause carries information. The parenthetical on found pets is dense and partly duplicates the schema's found description, costing some readability.

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 24-parameter tool with a nested place object and no output schema, the description states what is returned (names, facts, distance, rescue, link, q interpretation) and how empty results behave. Pagination and cursor semantics are left entirely to the schema, which is acceptable but a minor gap.

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 83%, so the baseline is 3, but the description adds value beyond the schema by enumerating the filter facets (species, age, size, sex, breed, color), the 10-language q behaviour, and the near-vs-country interaction. It also explains what q returns ('what q was understood as'), which no schema field states.

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 ('Search pets to adopt') plus the exact geographic inventory it covers and the facets it filters on. It only implicitly differentiates from siblings like show_pets and similar_pets, which surface solely via the limit default note and the search_by_description pointer inside a parameter description.

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?

Gives concrete usage conditions: 'No place and no country = everything we list', 'Nowhere else yet', and the default found behaviour (included, marked found:true, not adoptable). It also routes one alternative explicitly ('For such wishes prefer search_by_description'), but never says when to call this versus show_pets or similar_pets.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real value by disclosing ordering ('nearest first') and the returned fields (address, phone, website, adoptable-pets page, hours, directions, source, licence). It doesn't mention pagination or how many results come back by default, but the return-shape disclosure is unusually concrete for a tool with no output schema.

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?

Two sentences, front-loaded with the resource and locator formats, then the routing hint. The field list is dense but each item earns its place; only the trailing 'source and licence' pairing reads as 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?

With no output schema, the description sensibly enumerates return fields and input formats, and gives a usage trigger for a 5-parameter tool. It is slightly incomplete in not clarifying that all parameters are optional (0 required) or how the defaults for limit/radius_miles behave.

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 only 20%, so the description must carry the load; it explains the accepted locator formats (US ZIP, 'town, ST', or lat,lon), which maps onto near/lat/lon. However limit and radius_miles are undocumented in both the schema and the description, leaving half the parameters opaque.

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+resource ('shelters and rescues near...') and a distinctive scope ('that are not on Petnecto yet'), which separates it from find_pets and get_rescue. An agent knows exactly what this returns 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?

Gives an explicit trigger tied to a named sibling: 'Use it when find_pets finds nothing near the person.' Clear context and an alternative, though it doesn't state when NOT to use it (e.g. when find_pets does return results).

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real value: it discloses the payload contents (photos, stated facts, adoption fee, shelter contact) and the disambiguation behavior — 'Lists choices when an ID is shared' — which is a behavioral trait not captured anywhere in the structured fields.

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?

One dense sentence plus a short trailing clause; the identifier forms and the return contents are front-loaded before the edge-case behavior. No filler, though the trailing disambiguation sentence is slightly disjointed from the opener.

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 no output schema, the description usefully enumerates what comes back (photos, facts, fee, shelter and contact route), and it flags the ambiguous-ID case. For a simple two-parameter lookup this is essentially complete; only explicit routing guidance to sibling tools 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 both parameters are already documented, giving a baseline of 3. The description echoes the three accepted ID forms but adds no syntax, format, or validation nuance beyond what the schema states.

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+resource — retrieving ONE pet — and enumerates the accepted identifier forms (Petnecto ID, shelter pet ID, PetHarbor URL). The singular scope implicitly separates it from list-oriented siblings like find_pets and show_pets, though no sibling is named explicitly.

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?

Usage is implied by the identifier-based framing: use this when you already have an ID or URL, rather than searching. However, no explicit when-to-use/when-not statement or named alternative (e.g. find_pets for discovery) is given.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context by enumerating the response contents (location, adoption page, contact details) — notable since there is no output schema. Minor gap: no note on behavior for an unknown id.

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?

A single tight sentence that front-loads the verb+resource and then the payoff (what fields come back). No filler, 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 one-parameter lookup with no output schema, the description is nearly sufficient: it explains what is returned and where the input id comes from. It could say slightly more about behavior on an unmatched or malformed id, but nothing essential is absent.

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 schema coverage at 0%, the description carries the burden, and it does add real meaning: it tells the agent the id originates from a pet's 'rescue.id', which is not encoded anywhere in the schema. It doesn't restate the accepted id patterns, but the provenance is the more valuable missing piece.

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+resource ('One rescue or shelter by id') plus the key fields returned (location, adoption page, email, phone), so an agent knows exactly what this returns. It distinguishes itself from find_shelters_near by the 'by id' lookup, though it doesn't name that sibling explicitly.

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 parenthetical '(from a pet's rescue.id)' implies when to reach for it — after get_pet surfaces a rescue id — but there's no explicit when/when-not statement or named alternative to find_shelters_near. Usage is inferable rather than stated.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses data sparsity per locale (Taiwan lacks Baby/Senior ages, Vienna lacks sizes, good-with is rarely populated anywhere), which directly prevents an agent from proposing unusable filters. It stops short of 5 because nothing is said about result size, caching or freshness.

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?

Two sentences, no filler, and the resource scope is front-loaded before the caveats. The first sentence's clause 'how many live pets state each species, age, size...' is grammatically tangled and needs a second read, which keeps it out of the top band, but 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?

With zero parameters and no output schema, the description carries the burden of explaining the return shape and does so (per-country counts by attribute value), plus the locale-specific gaps. For a simple discovery endpoint this is sufficient, though a line about how to interpret counts (live listings only, current snapshot) would close the remaining gap.

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 tool takes zero parameters, so per the rubric the baseline is 4 and there is no parameter syntax for the description to compensate for. Nothing in the description misrepresents or adds noise to the (empty) parameter surface.

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 the specific resource (countries/places with listings) and what it returns (per-country counts of live pets across species, age, size, sex, colour, good-with values). An agent can tell this is a filter-availability/facet-discovery tool rather than a search tool. It does not explicitly distinguish itself from siblings such as about_this_service or resolve_place, so it falls short of a 5.

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 closing clause 'check here before suggesting a filter' gives an explicit usage trigger and ties the tool to the sibling family that suggests filters (find_pets, search_by_description). It does not name a when-not condition or an alternative to use instead, so it is clear context rather than full routing guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds the meaningful behavioral fact that the output is Wikidata breed ids usable as a cross-tool key — important since no output schema exists. It omits no-match/failure behavior and any rate or length limits.

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?

A single front-loaded sentence with no filler; the core action, input examples, output type, and downstream use all fit compactly.

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?

Covers the input concept and the return type, which partially compensates for the missing output schema. However, for a 2-parameter tool with a fully undocumented enum parameter and no guidance on unresolved names or species scoping, an agent is left guessing on important cases.

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 0%, so the description carries the full burden. It implicitly characterizes 'text' as a breed name in any language, but never mentions the 'species' parameter or its 8-value enum (Dog, Cat, Rabbit, ...), which is a significant omission for disambiguating names like 'Pig' or 'Bird'.

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 (resolve/turn) and resource (breed name in any language) with concrete multilingual examples (貴賓犬, pit bull, perro salchicha, 시바견) and names the output artifact (Wikidata breed ids). It is clearly distinct from siblings like resolve_place or find_pets.

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?

Gives explicit downstream context — pass the ids to find_pets as breed, or use them to compare listings across countries. That is clear when-to-use guidance tied to a named sibling, though it never states when not to use it (e.g. when a raw name string is already accepted).

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?

Goes beyond the readOnly/idempotent annotations with details those hints cannot convey: positions are rounded to about 1 km, nothing is stored, and the tool returns hits for regions with no pet listings so the agent is not misled by an empty result. That is exactly the kind of behavioral context annotations cannot 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?

Two sentences, front-loaded with the conversion action and followed by the caveat about uncovered places. The long example list ('Zaragoza, Wien or Fukushima') is somewhat wordy but does communicate accepted input variety and locale handling.

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 resolver with no output schema, the description does convey what comes back (a point) and its precision, plus the edge case where no pets exist nearby. Only the exact response structure is unspecified, a minor gap.

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 single parameter's description repeats the same examples as the tool description, so no meaning is added beyond the schema. The description implies the accepted formats and the length cap is schema-side, so baseline 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?

Names a specific verb and resource ('Turn ... into the point find_pets would search around') and enumerates accepted input forms, so an agent knows exactly what it converts. It explicitly names the sibling tool (find_pets) whose input this feeds, distinguishing it from search/listing siblings.

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?

States the workflow context clearly: resolve the place first so the person can confirm it before find_pets runs. It also notes that unpets-covered places still resolve and that find_pets will report the absence, which prevents an agent from skipping the step. It does not name an explicit alternative for when not to call it, keeping it below a 5.

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?

Well beyond the annotations, it explains match semantics (stated / inferred with a % / not_stated), that unstated pets are excluded and counted, and that findings marked found:true are not adoptable. The remaining gap is the approx/hint caveat being phrased tersely ('a chip noted approx or hint is not a fact about any pet') without saying how such chips affect match confidence.

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?

Purpose is front-loaded in the first clause, followed by match semantics, the off/chips mechanism, and the sibling alternative. It is dense and the third sentence is a run-on carrying several distinct facts, but essentially no sentence is 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?

There is no output schema, yet the description still explains the return shape an agent needs to act on: per-wish match statuses, understood.chips, and the found flag. Combined with the parameter coverage, an agent has enough to call it and interpret the result 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 75%, so the schema already documents near, country, lang and include_unknown. The description still adds cross-call meaning the schema cannot: 'off' works on chip ids from a previous answer's understood.chips, and include_unknown changes whether non-stating pets appear or are merely counted. It doesn't clarify paging behavior for page/limit.

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 ('find pets from wishes in the person's own words, in any language') and immediately scopes it to fuzzy/qualitative wishes rather than structured attributes. It also names the sibling it is not ('Prefer find_pets for structured values'), so an agent can route without opening either 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?

Explicitly says when to use it ('wishes listings rarely state, like calm or good with kids') and names the alternative plus the condition that selects it ('Prefer find_pets for structured values'). It also documents the recovery path (drop a wrong chip with off=[chip id]) and the include_unknown escape hatch, leaving little to inference.

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 readOnly/idempotent/non-destructive/openWorld, so the bar is lower. The description adds real context the annotations do not: the result is rendered as an interactive UI view, and 'apps without interactive views get the same list as text' tells the agent to expect a graceful degradation path rather than a failure. It stops short of describing pagination or result count behavior.

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-loaded with what the tool produces, then usage, then fallback behavior. No filler, though the parenthetical pointer to server instructions slightly dilutes the self-containedness.

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 10 optional params, four enums, and no output schema, the description needs to convey the return shape — and it does ('photos, facts, and a button', plus the text fallback). What's missing is only directional guidance versus the sibling find_pets, which is a usage gap rather than a completeness one.

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 80% and the schema descriptions already explain q, near, country, age, size, and good_with in detail. The description only echoes 'near a place', adding nothing about syntax, place formats, or the 'not nearby' fallback that the schema handles. 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?

States a specific verb and resource plus the distinctive output form: 'show pets to adopt near a place as an interactive view: photos, facts, and a button to meet one at its rescue'. That differentiates it from a plain list tool by output shape, but it never names the obvious sibling (find_pets) as the non-interactive counterpart, leaving the agent to infer the pairing.

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?

'Use it when someone wants to look at pets in a place we list (see the server instructions)' gives a when-condition, but the actual selection logic is deferred to external server instructions rather than stated. There is no exclusion, no mention of when to prefer find_pets or search_by_description instead.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that results are similarity-ranked from listing text, but says nothing about result count, ordering guarantees, or behavior when no similar pets exist.

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?

Two compact sentences with the core behavior front-loaded and the usage cue appended. "Nearest in meaning of their listings" is slightly awkward phrasing, but nothing 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?

For a read-only recommendation tool with no output schema, the description covers the essential trigger and similarity logic but leaves pagination/limit behavior and language handling unexplained. Adequate as a minimum, but an agent cannot tell how many results it will get or what to do with an empty set.

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 0% across 3 parameters, so the description carries the full burden. It adds real meaning for id (must come from search results), but lang and limit — including the 1-24 cap — are completely unaddressed in both schema and description.

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 concrete verb-like outcome and resource: pets similar to a given pet id, with the similarity criteria spelled out (same kind of pet and size, nearest listing meaning). This clearly distinguishes it from get_pet (single lookup) and find_pets/search_by_description, though it doesn't name those siblings explicitly.

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?

"Use it after the person likes one pet" gives a concrete trigger condition, and "(from search results)" tells the agent where the id comes from. It stops short of naming alternatives or saying when not to use it (e.g. cold-start recommendations with no liked pet).

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