Skip to main content
Glama

Browse the IC Vault of first-try recipes (public)

ic_vault_list
Read-only

List and filter the Immersive Commons Vault: procedures PROVEN to work, written so you clear them without exploring — agent-readiness playbooks and startup credit programs, same schema. No auth required. Filters: kind ('playbook'|'credit'), category, status ('proven'|'unproven'|'dead' — does the thing actually exist), evidence ('official'|'mixed'|'approx' — how well-sourced the facts are), verified_within_days (freshness), q (substring over title/summary/eligibility), sort, limit, offset. Returns: { ok, total, returned, offset, entries[], facets, notes }. Each entry carries first_try_success_label, which reads "not yet measured" — NOT "0%" — until an entry has enough real reports; first_try_success is null in that state and a client must not render it as a number. facets gives the live value counts per filter so you can narrow without guessing at the vocabulary. An unknown filter value is IGNORED and explained in notes rather than erroring. Use ic_vault_match to ask whether a specific company qualifies; use ic_vault_feedback_submit to report whether a recipe worked.

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

Input Schema

NameRequiredDescriptionDefault
qNoCase-insensitive substring over id, title, summary, category and eligibility prose.
kindNo'playbook' = a multi-step procedure with per-step verification and traps. 'credit' = a credit / discount / perk program with one or more offer tiers.
sortNo'recent' (default) = most recently verified first. 'status' = proven first.
limitNoDefault 100, max 200.
offsetNoDefault 0.
statusNoDoes the thing WORK / EXIST. 'proven' = someone ran it end to end. 'dead' = the named program does not exist and the entry is kept only so nobody chases it. This is a DIFFERENT axis from `evidence`.
categoryNoExact category string, case-insensitive. Read the live set from `facets.category` in any response rather than guessing — a miss returns an empty list plus the real values in `notes`.
evidenceNoHow well-sourced the FACTS are. 'official' = from the vendor's own page; 'approx' = aggregator/blog-sourced, verify before quoting. Orthogonal to `status`: a well-sourced entry about a dead program is official + dead.
verified_within_daysNoFreshness gate: keep only entries re-checked within N days. Note this is `last_verified` (when someone last looked), not `last_changed` (when the program last moved) — the two are deliberately not the same field.

Output Schema

NameRequiredDescriptionDefault
okNotrue when the call did what it was asked; false with `error` and `error_kind` when it did not
textNoThe tool's reply when it returns plain text instead of JSON
errorNoWhy the call failed, in a sentence a person can act on. Present only when ok is false.
resultNoThe tool's value when it returns a list or a single value instead of an object
error_kindNoMachine-readable failure class: no_token, missing_scope, forbidden, not_found, invalid_input, rate_limited or transient

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "description": "The tool's JSON result. Every field the tool's description names is present at the top level; ok, error and error_kind follow the shared envelope.",
      +  "properties": {
      +    "error": {
      +      "description": "Why the call failed, in a sentence a person can act on. Present only when ok is false."
      +    },
      +    "error_kind": {
      +      "description": "Machine-readable failure class: no_token, missing_scope, forbidden, not_found, invalid_input, rate_limited or transient"
      +    },
      +    "ok": {
      +      "description": "true when the call did what it was asked; false with `error` and `error_kind` when it did not"
      +    },
      +    "result": {
      +      "description": "The tool's value when it returns a list or a single value instead of an object"
      +    },
      +    "text": {
      +      "description": "The tool's reply when it returns plain text instead of JSON"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Added

TDQS

A4.4/5.0
Behavior4/5

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

Annotations cover read-only and closed-world, but the description adds non-obvious behavior: no auth required, and unknown filter values are silently IGNORED and explained in `notes` rather than erroring — a critical failure-mode disclosure. It also flags the first_try_success_label / null trap that a client could misrender as 0%, which is exactly the kind of rendering hazard annotations cannot convey. It stops short of pagination/perf characteristics, so not 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?

Purpose and the no-auth guarantee are front-loaded, then filters, then return shape, then the success-label caveat, then sibling routing — a sensible order. It is dense and slightly redundant where it re-enumerates the schema's filter vocabulary, but no sentence is 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?

The 9-parameter surface is fully accounted for, and although an output schema exists, the description still clarifies the two fields most likely to be misread (first_try_success_label, notes on ignored filters). An agent has everything needed to call it and interpret the response correctly.

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% and the description's filter list largely restates the schema's own enum documentation, so baseline 3 applies. It does add cross-parameter meaning (status and evidence as orthogonal axes; facets as a live vocabulary source) that helps an agent compose filters correctly, but the per-filter definitions themselves are duplicated rather than extended.

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 ('List and filter'), a named resource ('Immersive Commons Vault'), and its distinguishing scope: procedures proven to work plus credit programs under one schema. An agent can tell it apart from ic_vault_match (single-company qualification) without opening either schema.

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 routes the agent: use this to browse/filter, use ic_vault_match to ask whether a specific company qualifies, use ic_vault_feedback_submit to report outcomes. It also prescribes a workflow for vocabulary discovery ('read the live set from facets rather than guessing'), which prevents the main misuse mode.

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.