Skip to main content
Glama

Find Institution

find_institution
Read-only

Which institution is this? A name fragment or an IPEDS UNITID answers with the institution's identity, sector, identifiers with their sources, and how many programs, checklists, and learning units its published catalog holds here. A state lists that state's institutions by name; with no name and no state, the answer is the states that hold institutions, each with its count. Each row names its current FORM's wording source: source_url, capture_file, catalog_year and source_catalog_name are that one source's, never the record's whole span. A row whose record holds more than one form or more than one source also carries version_count, source_count, first_edition_seen and last_edition_seen, and one sentence saying so in words; a record with one form and one source carries none of them and reads exactly as it always has. The forms themselves, each with its own content and its own sources, come from the one-record get, never from a list. A record last seen in an older edition says so, because the Union keeps a record no current catalog prints.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cityNoOptional city, one of a state answer's cities, e.g. Denison
limitNoOptional page size (default 20, at most 100)
queryNoName fragment or IPEDS UNITID, e.g. Denver or 127060
stateNoOptional two-letter state, e.g. TX: that state's institutions, those with a catalog held first; the answer lists the state's cities
offsetNoOptional: the next_offset from a previous answer

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / city
      Added value: +{
      +  "description": "Optional city, one of a state answer's cities, e.g. Denison",
      +  "examples": [
      +    "Denison"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / state / description
      Previous value: -"Optional two-letter state, e.g. TX: that state's institutions by name"New value: +"Optional two-letter state, e.g. TX: that state's institutions, those with a catalog held first; the answer lists the state's cities"
  2. Changed2 schema fields changed
    • addedInput schema / properties / state
      Added value: +{
      +  "description": "Optional two-letter state, e.g. TX: that state's institutions by name",
      +  "examples": [
      +    "TX"
      +  ],
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "query"
      -]
  3. Changed1 schema field changed
    • addedInput schema / properties / query / examples
      Added value: +[
      +  "Grayson",
      +  "225070"
      +]
  4. Added

TDQS

B3.1/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=true, so the description carries the burden of behavioral disclosure. It adds substantial context: what each row includes (source metadata, version counts, first/last edition seen), that forms themselves come from a separate get, and that older-edition records are flagged. This is rich beyond the annotation, though it doesn't cover pagination defaults, error conditions, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly long and digressive, burying the core lookup behavior under details about form sources, version counts, and catalog editions that are tangential to the primary find operation. It is not front-loaded with the essential purpose; the first sentence is a question, and key routing information appears late. Several sentences could be trimmed or moved to related tools.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and only a readOnly annotation, the description does provide extensive behavioral detail about return values (row contents, source metadata, version indicators). However, it misses practical completeness for a search tool: no pagination explanation beyond schema defaults, no result limit behavior, and no guidance on handling empty results. The heavy focus on form/source nuances is likely more relevant to get_institution, suggesting misdirected completeness.

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 description coverage is 100%, so the schema already documents all five parameters with examples and defaults. The description adds interpretive value by explaining how parameters combine: query answers identity, state lists institutions, with no query/state it returns states with counts. This semantic integration goes beyond the schema's individual parameter descriptions, though it doesn't clarify parameter interactions like query+state or city+state.

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

Purpose3/5

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

The description conveys that this is a lookup tool for institutions answering by name fragment, IPEDS UNITID, or state, with sector and identifiers. However, the core purpose is buried under extensive detail about forms, sources, and versioning, making it harder to grasp quickly than a straightforward 'find institutions by X' statement. It doesn't clearly differentiate from sibling get_institution or find_programs, which likely retrieve a single record or related lists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives like get_institution or find_programs. The description implies a search/listing function but doesn't state 'use this to discover institutions' or exclude cases (e.g., 'use get_institution for full details on one institution'). No when-not-to-use or sibling routing is provided.

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.