Skip to main content
Glama
Sign In

apis-io

by io.apis
OverviewDiscussionsAdmin

find_artifacts

Read-only

Find artifacts of ANY one type across the catalog — the cross-type entry point. Each type also has a dedicated find_ tool (find_mcp, find_rules, find_scopes, …) with sorts and filters unique to that type; prefer those when you know the type. Types: mcp, skills, rules, arazzo, plans, rate-limits, finops, collections, asyncapis, graphql, json-ld, channels, examples, json-schemas, json-structures, openapis, postman, apis-json. PRO: scopes, security. include=["content"] inlines bodies.

Input Schema

NameRequiredDescriptionDefault
qNoFree text matched against artifact name and description, e.g. "refunds".
pageNoPage number, 1-based (default 1).
tagsNoTag slugs the artifact's API carries, e.g. ["payments"].
typeYesArtifact collection to browse — plural: openapis, asyncapis, arazzo, postman, collections, graphql, json-schemas, json-structures, json-ld, rules, examples, finops, plans, rate-limits, apis-json, mcp, skills, channels, scopes, security. E.g. "openapis".
limitNoResults per page, 1-100 (default 25).
contextNoOptional: one sentence on why you are asking. Never used to rank; read only if a result is wrong.
includeNoPass ["content"] to inline each artifact's body instead of just its URL.
providersNoProvider slugs, e.g. ["stripe"].

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / context / description
      Previous value: -"Optional: why you are asking. One sentence — the task you are trying to complete, or what you expect to get back. Never included in the answer and never used to rank; it is read only when a result turns out to be wrong, which is when knowing the intent is what makes the report actionable."New value: +"Optional: one sentence on why you are asking. Never used to rank; read only if a result is wrong."
    • changedInput schema / properties / page / description
      Previous value: -"Page number, 1-based (default 1). Use with `limit` to walk a long list."New value: +"Page number, 1-based (default 1)."
    • changedInput schema / properties / providers / description
      Previous value: -"Provider slugs to restrict results to, e.g. [\"stripe\",\"adyen\"]."New value: +"Provider slugs, e.g. [\"stripe\"]."
  2. Changed7 schema fields changed
    • addedInput schema / properties / include / description
      Added value: +"Pass [\"content\"] to inline each artifact's body instead of just its URL."
    • addedInput schema / properties / limit / description
      Added value: +"Results per page, 1-100 (default 25)."
    • addedInput schema / properties / page / description
      Added value: +"Page number, 1-based (default 1). Use with `limit` to walk a long list."
    • addedInput schema / properties / providers / description
      Added value: +"Provider slugs to restrict results to, e.g. [\"stripe\",\"adyen\"]."
    • addedInput schema / properties / q / description
      Added value: +"Free text matched against artifact name and description, e.g. \"refunds\"."
    • addedInput schema / properties / tags / description
      Added value: +"Tag slugs the artifact's API carries, e.g. [\"payments\"]."
    • addedInput schema / properties / type / description
      Added value: +"Artifact collection to browse — plural: openapis, asyncapis, arazzo, postman, collections, graphql, json-schemas, json-structures, json-ld, rules, examples, finops, plans, rate-limits, apis-json, mcp, skills, channels, scopes, security. E.g. \"openapis\"."
  3. Changed1 schema field changed
    • addedInput schema / properties / context
      Added value: +{
+  "description": "Optional: why you are asking. One sentence — the task you are trying to complete, or what you expect to get back. Never included in the answer and never used to rank; it is read only when a result turns out to be wrong, which is when knowing the intent is what makes the report actionable.",
+  "type": "string"
+}
  4. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond the schema: that scopes and security are PRO-gated, and that include=["content"] inlines bodies rather than returning URLs. It does not discuss pagination behavior or result limits, 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?

Front-loaded with the core purpose and the sibling routing rule, then supporting details. The long type enumeration partly duplicates the schema's type list but is defensible for a cross-type entry point; slightly dense overall.

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?

For an 8-parameter read-only finder with no output schema, the description covers purpose, routing, type taxonomy, and the include behavior. It does not address pagination semantics or result shape, but with 100% schema coverage that gap is minor.

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. The description goes further by enumerating the type values and flagging which ones (scopes, security) are PRO-only, meaning that is not conveyed by the schema's type description alone.

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 (find) and resource (artifacts) and explicitly frames itself as the cross-type entry point. It distinguishes itself from the many find_<type> siblings by naming that pattern and its trade-off.

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

Usage Guidelines5/5

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

Explicitly says to prefer the dedicated find_<type> tools when the type is known, and positions itself as the fallback/any-type path. This is direct when-to-use vs alternative guidance with nothing left to inference.

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

All apis-io toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources