Skip to main content
Glama

Find pets to adopt

find_pets
Read-onlyIdempotent

Search pets to adopt in the places we list (Taiwan, King County WA, Montgomery County MD, Zaragoza, Fukushima Prefecture, and Vienna, found pets only: marked found:true, not adoptable yet; found=exclude leaves them out). Nowhere else yet. Search near a place (nearest first), by species, age, size, sex, breed and color, or by words in any of 10 languages (q). No place and no country = everything we list. Returns names, short facts, distance, the rescue and a link to each listing, plus what q was understood as; an empty answer says what we do list.

Input Schema

NameRequiredDescriptionDefault
qNoWords in the person's language: breeds, colors, ages, sizes, sex and places become filters, the rest is full-text ("黑色柴犬")
kmNoRadius, kilometres
ageNoTaiwan says only Young or Adult
sexNo
langNoThe person's language: en, es, zh-Hant, zh-Hans, ko, ja, vi, fr, ar, tl (default en)
nearNoa Taiwan county or township in any language, a US ZIP, Zaragoza, Wien or Fukushima (福島県) (98101, 信義區, 臺北市), or lat,lon; never a street address. Nearest first; an uncovered place gets the nearest pets we hold, marked not nearby
pageNo
sizeNoNot stated in King County or Vienna
sortNophoto = best photo first
breedNoBreed name in any language, or Wikidata id
colorNo
foundNoFound pets (Vienna's, announced for their owners first) are included by default, marked found:true, NOT adoptable. exclude = adoptable only. Never call one adoptable
limitNoPets per answer (find_pets default 10, show_pets 24)
milesNoRadius, miles (default 50)
photoNogood: only pets whose best photo passed our checks; unanalysed pets are left out (only Taiwan's are analysed)
placeNonear as structured fields; never a street address
cursorNonext_cursor from the previous answer
detailNofind_pets default brief; full = every field of pet.v1
facetsNoAdd counts by species, size, age, sex, region
regionNoTaiwan county or city, e.g. Taipei City
countryNoTW (Taiwan), US (King County WA, Montgomery County MD only), ES (Zaragoza), AT (Vienna, found pets only) or JP (Fukushima Prefecture). Not needed with near
speciesNo
good_withNoOnly pets whose listing says so; rarely stated. kids is not offered; if it is passed anyway, the answer lists pets whose listing does not say (good_with_soft, each not_stated). For such wishes prefer search_by_description
min_photo_pxNoBest photo's longest side, at least, in pixels

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"TW, US (King County WA, Montgomery County MD only), ES (Zaragoza) or AT (Vienna, found pets only). Not needed with near"New value: +"TW (Taiwan), US (King County WA, Montgomery County MD only), ES (Zaragoza), AT (Vienna, found pets only) or JP (Fukushima Prefecture). Not needed with near"
    • changedInput schema / properties / country / enum
      Previous value: -[
      -  "TW",
      -  "US",
      -  "ES",
      -  "AT"
      -]New value: +[
      +  "TW",
      +  "US",
      +  "ES",
      +  "AT",
      +  "JP"
      +]
    • changedInput schema / properties / near / description
      Previous value: -"A US ZIP (98101), lat,lon, a Taiwan county or township in any language (信義區, 臺北市), Zaragoza or Wien; never a street address. Nearest first; an uncovered place gets the nearest pets we hold, marked not nearby"New value: +"a Taiwan county or township in any language, a US ZIP, Zaragoza, Wien or Fukushima (福島県) (98101, 信義區, 臺北市), or lat,lon; never a street address. Nearest first; an uncovered place gets the nearest pets we hold, marked not nearby"
    • changedInput schema / properties / place / properties / area / description
      Previous value: -"A Taiwan county or township, Zaragoza or Wien"New value: +"a Taiwan county or township in any language, a US ZIP, Zaragoza, Wien or Fukushima (福島県)"
  2. Changed21 schema fields changed
    • changedInput schema / properties / age / description
      Previous value: -"Taiwan's shelters say only Young or Adult"New value: +"Taiwan says only Young or Adult"
    • changedInput schema / properties / breed / description
      Previous value: -"A breed name in any language, or its Wikidata id (Q39315)"New value: +"Breed name in any language, or Wikidata id"
    • changedInput schema / properties / country / description
      Previous value: -"Which country's listings: TW (Taiwan, every public shelter), US (King County WA and Montgomery County MD only), ES (Zaragoza) or AT (Vienna, found pets only). Not needed with near"New value: +"TW, US (King County WA, Montgomery County MD only), ES (Zaragoza) or AT (Vienna, found pets only). Not needed with near"
    • changedInput schema / properties / cursor / description
      Previous value: -"next_cursor from the previous answer: the next page, without re-reading the earlier ones"New value: +"next_cursor from the previous answer"
    • changedInput schema / properties / detail / description
      Previous value: -"find_pets default brief (short pets; get_pet has the full record); full = every field of pet.v1"New value: +"find_pets default brief; full = every field of pet.v1"
    • changedInput schema / properties / facets / description
      Previous value: -"Add counts by species, size, age, sex, region and good-with"New value: +"Add counts by species, size, age, sex, region"
    • changedInput schema / properties / found / description
      Previous value: -"Found pets (Vienna's list, announced for their owners first; a pet can stay listed for months) are included by default, each marked found:true and NOT adoptable yet. exclude = adoptable pets only; only = found pets only. Never call a found pet adoptable"New value: +"Found pets (Vienna's, announced for their owners first) are included by default, marked found:true, NOT adoptable. exclude = adoptable only. Never call one adoptable"
    • changedInput schema / properties / good_with / description
      Previous value: -"Only pets whose listing says so. Rarely stated: a few dozen Taiwan listings, none elsewhere. No listing states good with kids, so kids is not offered; if it is passed anyway, the answer lists pets whose listing does not say (good_with_soft, each not_stated) and says so. For such wishes prefer search_by_description (stated / not_stated per pet)"New value: +"Only pets whose listing says so; rarely stated. kids is not offered; if it is passed anyway, the answer lists pets whose listing does not say (good_with_soft, each not_stated). For such wishes prefer search_by_description"
    • changedInput schema / properties / km / description
      Previous value: -"Radius in kilometres, instead of miles"New value: +"Radius, kilometres"
    • changedInput schema / properties / lang / description
      Previous value: -"The person's language for names and text: en, es, zh-Hant, zh-Hans, ko, ja, vi, fr, ar, tl (default en)"New value: +"The person's language: en, es, zh-Hant, zh-Hans, ko, ja, vi, fr, ar, tl (default en)"
    • changedInput schema / properties / miles / description
      Previous value: -"Radius in miles (default 50)"New value: +"Radius, miles (default 50)"
    • changedInput schema / properties / min_photo_px / description
      Previous value: -"Only pets whose best photo is at least this many pixels on its longest side"New value: +"Best photo's longest side, at least, in pixels"
    • changedInput schema / properties / near / description
      Previous value: -"Where the person is: a US ZIP (98101, 20850), lat,lon (25.03,121.56; rounded to ~1 km), a Taiwan county or township in any language (信義區, Xinyi, 臺北市), Zaragoza or Wien. Sorted by distance; a place we do not cover gets the nearest pets we hold, marked as not nearby. Prefer this or place over free text"New value: +"A US ZIP (98101), lat,lon, a Taiwan county or township in any language (信義區, 臺北市), Zaragoza or Wien; never a street address. Nearest first; an uncovered place gets the nearest pets we hold, marked not nearby"
    • changedInput schema / properties / photo / description
      Previous value: -"good: only pets whose best photo passed our checks (analysed; not blurry, dark, tiny, or without a pet in it). Pets not analysed yet are left out, and so far only Taiwan's photos are analysed"New value: +"good: only pets whose best photo passed our checks; unanalysed pets are left out (only Taiwan's are analysed)"
    • changedInput schema / properties / place / description
      Previous value: -"The same as near, as structured fields (do not put a street address or a whole sentence here; the server resolves it against its own place table)"New value: +"near as structured fields; never a street address"
    • changedInput schema / properties / place / properties / area / description
      Previous value: -"A Taiwan county or township in any language, Zaragoza or Wien"New value: +"A Taiwan county or township, Zaragoza or Wien"
    • changedInput schema / properties / place / properties / latitude / description
      Previous value: -"Only with longitude, and only if the person shared their location"New value: +"Only with longitude, if the person shared it"
    • changedInput schema / properties / place / properties / postal_code / description
      Previous value: -"A US ZIP (we list King County WA and Montgomery County MD only)"New value: +"A US ZIP"
    • changedInput schema / properties / q / description
      Previous value: -"Words in the person's own language: breeds, colors, ages, sizes, sex and places become filters (\"black shiba girl\", \"黑色柴犬\", \"perro mayor\"); other words are full-text search"New value: +"Words in the person's language: breeds, colors, ages, sizes, sex and places become filters, the rest is full-text (\"黑色柴犬\")"
    • changedInput schema / properties / region / description
      Previous value: -"Taiwan county or city, e.g. Taipei City, New Taipei City, Taoyuan City"New value: +"Taiwan county or city, e.g. Taipei City"
    • changedInput schema / properties / sort / description
      Previous value: -"distance is the default when near is given and needs it; photo = best photo first"New value: +"photo = best photo first"
  3. Changed1 schema field changed
    • changedInput schema / properties / found / description
      Previous value: -"Found pets (Vienna's list, announced for their owners for 30 days) are included by default, each marked found:true and NOT adoptable yet. exclude = adoptable pets only; only = found pets only. Never call a found pet adoptable"New value: +"Found pets (Vienna's list, announced for their owners first; a pet can stay listed for months) are included by default, each marked found:true and NOT adoptable yet. exclude = adoptable pets only; only = found pets only. Never call a found pet adoptable"
  4. Changed2 schema fields changed
    • changedInput schema / properties / good_with / description
      Previous value: -"Only pets whose listing says so. Rarely stated: a few dozen Taiwan listings, none elsewhere; no listing states good with kids, so it is not offered. For such wishes prefer search_by_description (stated / not_stated per pet)"New value: +"Only pets whose listing says so. Rarely stated: a few dozen Taiwan listings, none elsewhere. No listing states good with kids, so kids is not offered; if it is passed anyway, the answer lists pets whose listing does not say (good_with_soft, each not_stated) and says so. For such wishes prefer search_by_description (stated / not_stated per pet)"
    • changedInput schema / properties / good_with / maxItems
      Previous value: -2New value: +3
  5. Changed18 schema fields changed
    • addedInput schema / properties / age / description
      Added value: +"Taiwan's shelters say only Young or Adult"
    • changedInput schema / properties / country / description
      Previous value: -"Which country's shelters: US, CA, TW (Taiwan), ES (Spain) or AT (Austria). Optional when near is a US ZIP or a Taiwan place"New value: +"Which country's listings: TW (Taiwan, every public shelter), US (King County WA and Montgomery County MD only), ES (Zaragoza) or AT (Vienna, found pets only). Not needed with near"
    • changedInput schema / properties / country / enum
      Previous value: -[
      -  "US",
      -  "CA",
      -  "TW",
      -  "ES",
      -  "AT"
      -]New value: +[
      +  "TW",
      +  "US",
      +  "ES",
      +  "AT"
      +]
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "next_cursor from the previous answer: the next page, without re-reading the earlier ones",
      +  "maxLength": 80,
      +  "type": "string"
      +}
    • addedInput schema / properties / detail
      Added value: +{
      +  "description": "find_pets default brief (short pets; get_pet has the full record); full = every field of pet.v1",
      +  "enum": [
      +    "brief",
      +    "full"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / good_with / description
      Previous value: -"Only pets the rescue says are good with these"New value: +"Only pets whose listing says so. Rarely stated: a few dozen Taiwan listings, none elsewhere; no listing states good with kids, so it is not offered. For such wishes prefer search_by_description (stated / not_stated per pet)"
    • changedInput schema / properties / good_with / items / enum
      Previous value: -[
      -  "dogs",
      -  "cats",
      -  "kids"
      -]New value: +[
      +  "dogs",
      +  "cats"
      +]
    • changedInput schema / properties / good_with / maxItems
      Previous value: -3New value: +2
    • addedInput schema / properties / limit / description
      Added value: +"Pets per answer (find_pets default 10, show_pets 24)"
    • changedInput schema / properties / near / description
      Previous value: -"Where the person is: a US ZIP (65738), lat,lon (25.03,121.56; rounded to ~1 km), or a Taiwan county or township in any language (信義區, Xinyi, 臺北市). Results are sorted by distance. Prefer this or place over free text"New value: +"Where the person is: a US ZIP (98101, 20850), lat,lon (25.03,121.56; rounded to ~1 km), a Taiwan county or township in any language (信義區, Xinyi, 臺北市), Zaragoza or Wien. Sorted by distance; a place we do not cover gets the nearest pets we hold, marked as not nearby. Prefer this or place over free text"
    • changedInput schema / properties / page / maximum
      Previous value: -100New value: +10000
    • changedInput schema / properties / photo / description
      Previous value: -"good: only pets whose best photo passed our checks (analysed; not blurry, dark, tiny, or without a pet in it). Pets not analysed yet are left out"New value: +"good: only pets whose best photo passed our checks (analysed; not blurry, dark, tiny, or without a pet in it). Pets not analysed yet are left out, and so far only Taiwan's photos are analysed"
    • changedInput schema / properties / place / properties / area / description
      Previous value: -"A Taiwan county or township, in any language"New value: +"A Taiwan county or township in any language, Zaragoza or Wien"
    • changedInput schema / properties / place / properties / postal_code / description
      Previous value: -"US ZIP or Canadian postal code"New value: +"A US ZIP (we list King County WA and Montgomery County MD only)"
    • changedInput schema / properties / q / description
      Previous value: -"Words in the person's own language: breeds, colors, ages, sizes, sex and places become filters (\"black shiba girl Taipei\", \"黑色柴犬\", \"perro mayor\"); other words are full-text search"New value: +"Words in the person's own language: breeds, colors, ages, sizes, sex and places become filters (\"black shiba girl\", \"黑色柴犬\", \"perro mayor\"); other words are full-text search"
    • addedInput schema / properties / size / description
      Added value: +"Not stated in King County or Vienna"
    • changedInput schema / properties / sort / description
      Previous value: -"photo = best photo first"New value: +"distance is the default when near is given and needs it; photo = best photo first"
    • changedInput schema / properties / species / enum
      Previous value: -[
      -  "Dog",
      -  "Cat",
      -  "Rabbit",
      -  "Bird",
      -  "Horse",
      -  "Small pet",
      -  "Reptile",
      -  "Pig",
      -  "Barnyard"
      -]New value: +[
      +  "Dog",
      +  "Cat",
      +  "Rabbit",
      +  "Bird",
      +  "Small pet",
      +  "Reptile",
      +  "Pig",
      +  "Barnyard"
      +]
  6. Changed8 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Which country's shelters: US, CA or TW (Taiwan). Optional when near is a US ZIP or a Taiwan place"New value: +"Which country's shelters: US, CA, TW (Taiwan), ES (Spain) or AT (Austria). Optional when near is a US ZIP or a Taiwan place"
    • changedInput schema / properties / country / enum
      Previous value: -[
      -  "US",
      -  "CA",
      -  "TW"
      -]New value: +[
      +  "US",
      +  "CA",
      +  "TW",
      +  "ES",
      +  "AT"
      +]
    • addedInput schema / properties / found
      Added value: +{
      +  "description": "Found pets (Vienna's list, announced for their owners for 30 days) are included by default, each marked found:true and NOT adoptable yet. exclude = adoptable pets only; only = found pets only. Never call a found pet adoptable",
      +  "enum": [
      +    "include",
      +    "exclude",
      +    "only"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / min_photo_px
      Added value: +{
      +  "description": "Only pets whose best photo is at least this many pixels on its longest side",
      +  "maximum": 4000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / photo
      Added value: +{
      +  "description": "good: only pets whose best photo passed our checks (analysed; not blurry, dark, tiny, or without a pet in it). Pets not analysed yet are left out",
      +  "enum": [
      +    "good"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / sort / description
      Added value: +"photo = best photo first"
    • changedInput schema / properties / sort / enum
      Previous value: -[
      -  "relevance",
      -  "newest",
      -  "distance"
      -]New value: +[
      +  "relevance",
      +  "newest",
      +  "listed",
      +  "distance",
      +  "photo"
      +]
    • changedInput schema / properties / species / enum
      Previous value: -[
      -  "Dog",
      -  "Cat",
      -  "Rabbit",
      -  "Bird",
      -  "Horse",
      -  "Small animal",
      -  "Reptile",
      -  "Pig",
      -  "Barnyard"
      -]New value: +[
      +  "Dog",
      +  "Cat",
      +  "Rabbit",
      +  "Bird",
      +  "Horse",
      +  "Small pet",
      +  "Reptile",
      +  "Pig",
      +  "Barnyard"
      +]
  7. First observed

TDQS

A4.2/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources