Skip to main content
Glama

Search specs

search_specs
Read-onlyIdempotent

Finds specs on Spekkr by words, the best match first, with each one's id, summary and platforms. Most build a part of an app; a spec that builds something else, such as a CAD model, a circuit or an animation, says so under kind. Search with a few words that name the thing, such as "sign in" or "sliding puzzle"; a slip in a long word is forgiven. When no spec holds every word, the specs that hold some of them are returned and partial is true. Leave query out to list the specs, the ones pulled most first. An answer holds at most limit specs: total counts the specs that matched, and offset reads further into them. catalogTotal counts every spec there is. A spec with publishedBy was published by a member.

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": "search_specs"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoOnly specs of this kind, such as CAD or animation. Each spec names its kind in its own words, so any text is allowed; capitals are ignored. A spec that names no kind builds software.
limitNoHow many specs to return at most. 20 when left out.
queryNoWords to look for in a spec's name, keywords, id, kind, stack, summary and platforms. A word may be only the start of one. Small words such as "the" and "for" are left out.
offsetNoHow many of the specs that matched to pass over first. 0 when left out.
platformNoOnly specs that target this platform.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Well beyond the annotations, it discloses result ordering ("the best match first"), typo tolerance ("a slip in a long word is forgiven"), the fallback behavior when no spec holds every word and the resulting partial=true flag, and what total/catalogTotal/publishedBy mean. It does not mention error cases or rate limits, which keeps it short of a 5 given annotations already cover the safety profile.

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 purpose and matching behavior, then pagination and field meanings; nearly every sentence carries information. The aside about specs building "a part of an app" versus CAD models/circuits is slightly wordy but earns its place by explaining the kind field. Dense but readable, without filler.

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

Completeness5/5

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

No output schema exists, and the description compensates by naming the fields an answer contains (id, summary, platforms, total, catalogTotal, partial, publishedBy) and explaining how offset/total interact. Combined with the 100%-covered input schema and read-only annotations, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds real meaning: fuzzy matching on words, what limit and offset do to the result envelope, and that kind only reflects self-described kinds. Those additions clarify how query and kind actually behave at runtime rather than restating the 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?

States a specific verb and resource ("Finds specs on Spekkr by words") plus what each result contains (id, summary, platforms), which lets an agent tell it apart from get_spec/check_spec, which fetch a single known spec. It does not name a sibling explicitly, and the listing mode ("Leave query out to list the specs") is mentioned but not contrasted with list-oriented siblings.

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 when-to-use guidance: search with a few naming words like "sign in" or "sliding puzzle", and omit query to browse popular specs instead. It never states when NOT to use it or which sibling to pick for fetching a specific spec by id, so there is a small gap, but the primary usage contexts are clear.

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