Skip to main content
Glama

Search Observations

search_observations
Read-onlyIdempotent

Search citizen-science wildlife observations on iNaturalist, ANY organism: plants, fungi, insects, birds, mammals, reptiles, amphibians. This is the tool for "sightings/observations of in in ". Filter by taxon name (scientific or common, e.g. "Leucanthemum vulgare"/"oxeye daisy", "Pandion haliaetus"/"osprey"), place name ("Yukon", "California"), year, threatened status, or quality grade. Returns photographed sightings with coordinates, dates, and observer info. Pairs well with GBIF for cross-validation.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "place": "California",
      "taxon_name": "Pandion haliaetus",
      "quality_grade": "research"
    },
    "name": "search_observations"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoFilter to a specific year
placeNoPlace name (country, state, park). Auto-resolved to place_id.
per_pageNoResults per page (1-200, default 20)
taxon_nameNoScientific or common species/taxon name
threatenedNoRestrict to IUCN-threatened taxa
quality_gradeNocasual | needs_id | research (default: research)

Output Schema

NameRequiredDescriptionDefault
resolvedYesResolved taxon and place IDs from input names
observationsYesArray of observation records
total_resultsYesTotal observation count matching filters

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / resolved / properties / taxon / properties / rank
      Added value: +{
      +  "description": "Taxonomic rank of the resolved taxon (species, genus, family, ...)",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. Changed2 schema fields changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "place": "California",
      +    "quality_grade": "research",
      +    "taxon_name": "Pandion haliaetus"
      +  },
      +  {
      +    "per_page": 50,
      +    "taxon_name": "osprey",
      +    "threatened": true,
      +    "year": 2023
      +  }
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "observations": {
      +      "description": "Array of observation records",
      +      "items": {
      +        "properties": {
      +          "id": {
      +            "description": "Observation ID",
      +            "type": "number"
      +          },
      +          "latitude": {
      +            "description": "Latitude coordinate",
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "longitude": {
      +            "description": "Longitude coordinate",
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "observed_on": {
      +            "description": "ISO date observed",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "observer": {
      +            "description": "Observer login name",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "photo": {
      +            "description": "Photo URL",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "place": {
      +            "description": "Place guess from observation",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "quality_grade": {
      +            "description": "Quality grade (casual, needs_id, research)",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "taxon": {
      +            "properties": {
      +              "common_name": {
      +                "description": "Common name",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "id": {
      +                "description": "Taxon ID",
      +                "type": "number"
      +              },
      +              "rank": {
      +                "description": "Taxonomic rank",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "scientific_name": {
      +                "description": "Scientific name",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "url": {
      +            "description": "iNaturalist observation URL",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "resolved": {
      +      "description": "Resolved taxon and place IDs from input names",
      +      "properties": {
      +        "place": {
      +          "properties": {
      +            "id": {
      +              "description": "iNaturalist place ID",
      +              "type": "number"
      +            },
      +            "name": {
      +              "description": "Place name",
      +              "type": "string"
      +            }
      +          },
      +          "type": "object"
      +        },
      +        "taxon": {
      +          "properties": {
      +            "id": {
      +              "description": "iNaturalist taxon ID",
      +              "type": "number"
      +            },
      +            "name": {
      +              "description": "Taxon name",
      +              "type": "string"
      +            }
      +          },
      +          "type": "object"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "total_results": {
      +      "description": "Total observation count matching filters",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "resolved",
      +    "total_results",
      +    "observations"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: results are photographed sightings containing coordinates, dates and observer info, and there is an implicit default quality grade. It does not discuss rate limits, pagination or result caps, keeping it from a 5.

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?

Purpose and query pattern are front-loaded, then filters, then return shape, then workflow. The organism enumeration ('plants, fungi, insects, birds, mammals, reptiles, amphibians') is somewhat long, but it serves recall for a domain-broad tool, so the sentence still earns its place.

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?

With an output schema present, the description need not enumerate return values, yet it still summarizes them briefly. For a 6-parameter, fully optional-filter search tool, the description covers purpose, filters and downstream use adequately; only pagination/limits are left entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already carries a description, so the baseline is 3. The description reinforces that taxon_name accepts scientific or common names with paired examples ('Leucanthemum vulgare'/'oxeye daisy') and that place accepts country/state/park names, but this largely repeats schema content rather than adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search citizen-science wildlife observations on iNaturalist') and scopes it broadly ('ANY organism: plants, fungi, insects, birds, mammals, reptiles, amphibians'). It also names the query shape it answers ('sightings/observations of <species> in <place> in <year>'), which separates it from the taxon-lookup sibling inaturalist_search_taxa.

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 a concrete when-to-use template ('This is the tool for "sightings/observations of <species> in <place> in <year>"') and a follow-on workflow hint ('Pairs well with GBIF for cross-validation'). It does not state when NOT to use it or explicitly contrast with the sibling taxa tool, so it stops short of a 5.

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.