Skip to main content
Glama

Describe the schema

describe_schema
Read-onlyIdempotent

Describes design record classes and their fields at a commit, or details one class's field types and documentation, helping you interpret records or choose the right class for queries.

Instructions

The kinds of record the design holds and their fields, at a commit. Without a class: every class by category (artifacts such as objectives and items; relationships such as prerequisites and placements, which carry their own rationale; infrastructure) with its own field names. With a class: that class in full, each field's type and documentation, inherited fields included. Use it to learn what a field means before reading records, or which class to pass to find_records.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "describe_schema"
  }
}

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.
classNoOne class to describe in full. Leave out for the summary of every class.
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.

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=true, idempotentHint=true, openWorldHint=false and non-destructive, so safety behavior is fully covered elsewhere. The description adds genuinely useful behavioral context beyond that: results are snapshotted at a commit, inherited fields are included, and relationships carry their own rationale. It still says nothing about response size or pagination for the all-classes summary, which is the heavier call.

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?

Three sentences, front-loaded with the return shape, then the two modes, then the usage pointer. The parenthetical class examples ('objectives and items; prerequisites and placements...') earn their place by showing the categorization scheme. Density is high but nothing is clearly redundant.

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?

There is no output schema, so the description must explain returns driven by the class parameter, and it does: categorized summary versus one class with types, docs and inherited fields. Combined with annotations covering the safety profile and a fully documented schema, an agent has what it needs. It stops short of describing the summary's structure in detail, which is the one remaining gap.

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 description coverage is 100%, so the schema already documents ref, class and branch, including the mutual exclusivity of ref and branch and the enum of 30 classes. The description adds the meaningful semantic point that omitting class yields a categorized summary versus full detail with per-field type and documentation, and that inherited fields appear. That is real added meaning but modest against an already complete schema.

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 description names the resource precisely ('the kinds of record the design holds and their fields, at a commit') and splits the two modes: all classes by category without a class, one class in full with a class. It differentiates itself from siblings by routing class discovery toward find_records. The only small weakness is that the opening noun phrase is slightly indirect rather than a clean verb+resource statement.

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?

It gives explicit when-to-use guidance: 'use it to learn what a field means before reading records, or which class to pass to find_records.' That covers the two main entry points (pre-read schema lookup and sibling routing). It does not state when-not to use it, but the guidance is concrete enough to be actionable.

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