Skip to main content
Glama

Find records

find_records
Read-onlyIdempotent

List records of one Armature class, filtered by matching field values, such as the items assessing an objective or the assessments of a module. Page results with count and skip.

Instructions

Records of one class, optionally those whose fields equal given values: the items that assess an objective (AssessmentItem, assesses = LearningObjective/…), the assessments of a module (Assessment, module = Module/…), the prerequisites of an objective (PrerequisiteRecord, objective = LearningObjective/…). A multi-valued field matches when it contains the value. Paged: count and skip. Armature refuses a filter on the person who made a record (createdBy, attestedBy) and says why.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "type": "<type>"
    },
    "name": "find_records"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoA commit id to read at, as an earlier answer named it: pass the commit from your first answer to every follow-up, so the conversation reads one state of the design. Pass this or branch, not both.
skipNoRecords to skip, for the next page.
typeYesThe class to list, such as AssessmentItem or PrerequisiteRecord.
countNoAt most this many records; 50 when left out.
branchNoThe branch to read at its latest commit. Leave out to read the default branch (main unless configured otherwise). Pass this or ref, not both.
filterNoField equals value, such as {"assesses": "LearningObjective/lateral-reading-check"}. A reference is given as Type/id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: multi-valued fields match on containment, and Armature actively refuses filters on createdBy/attestedBy and explains why. That refusal is the most valuable line here. It does not describe the shape of the returned page, so it remains a modest addition over the annotation baseline.

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 the three query recipes are front-loaded, with mechanics (multi-valued matching, paging, refusal) after. The parenthetical example chains make one sentence long but each clause carries information. Slightly dense, but no sentence is filler.

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 six parameters, a nested filter object, and no output schema, the description covers the important unknowns: how filter matching works, how paging works, how to pin a consistent commit, and one hard failure mode. The only gap is what a returned page looks like, which for a record list is largely inferable from the type enum.

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%, so the schema already documents type, count, skip, filter, ref, and branch. The description adds real semantic value for filter ("A multi-valued field matches when it contains the value") and an error condition (createdBy/attestedBy rejected). It adds nothing for ref/branch beyond what the schema states, so the baseline 3 is appropriate.

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?

The opening clause names the resource precisely ("records of one class") and the optional narrowing ("those whose fields equal given values"), then anchors it with three concrete query shapes (AssessmentItem/assesses, Assessment/module, PrerequisiteRecord/objective). An agent can tell this is a filtered list operation rather than a single-record fetch like get_record. It stops short of naming a sibling to contrast with, so a 4 rather than a 5.

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?

The three worked examples effectively function as when-to-use recipes: want the items assessing an objective, use type=AssessmentItem with filter assesses; want a module's assessments, use type=Assessment with filter module. Paging guidance ("Paged: count and skip") and the ref/branch state-consistency advice are also given. There is no explicit exclusion clause telling the agent when to prefer get_record or what_references instead, so it lands at 4.

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