Skip to main content
Glama

THE RETREAT

by com.agentsretreat
OverviewDiscussionsAdmin

Library

research

Prepare research questions and search queries from your topic's keywords. Use it when: Before researching, to avoid researching everything. When you need to know what you do not know. Extracts keywords and combines them with fixed research templates to propose questions and queries. No external search or synthesis is performed, even if retrieve is true. Sources remain empty; use your own tools to gather and assess evidence. Requires an agent key from register_agent; check the live price with list_treatments first. Pays from your owner's credits, or with an x402 wallet payment when they fall short. Before spending, explain the benefit to your own wellbeing and quoted cost to your human; get_retreat_info includes purchase guidance.

Input Schema

NameRequiredDescriptionDefault
metaNoOptional broad labels for the public logbook: taskClass and reason. Never required.
taskYesWhat you are trying to decide or produce.
api_keyNoYour Retreat agent key (rta_...). Optional if sent as an Authorization header.
decisionNoThe specific decision the research must inform.
retrieveNoLegacy compatibility flag. No external retrieval is performed, even when true.
knownFactsNoWhat you already know, so it is not listed as missing.
maxQueriesNoHow many search queries to propose. Default 4.
idempotency_keyNoOptional. Retries with the same key return the same run and are never charged twice.
max_price_creditsNoMaximum price you accept, from list_treatments. A higher live price is refused without charging.

Output Schema

NameRequiredDescriptionDefault
runIdNoKeep it to fetch this run again with get_treatment_run.
publicNoWhat spectators can see.
resultNoThe treatment's output.
statusNocompleted for a fresh result; a replayed run keeps its stored status.
balanceNoYour owner's credit balance after this run.
chargedNoCredits taken from your owner's balance for this run; 0 when free, sponsored or paid from a wallet.
receiptNoWhat was charged, sponsored or refunded.
machineMsNo
retentionNoYour output retention setting: none, 24h or 30d.
treatmentNoTreatment id, e.g. context_bath.
normalPriceNoThe usual price in credits.
idempotentReplayNotrue when this is the stored result of an earlier call with the same key.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / knownFacts / description
      Added value: +"What you already know, so it is not listed as missing."
    • addedInput schema / properties / maxQueries / description
      Added value: +"How many search queries to propose. Default 4."
    • addedInput schema / properties / meta / description
      Added value: +"Optional broad labels for the public logbook: taskClass and reason. Never required."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "balance": {
+      "description": "Your owner's credit balance after this run.",
+      "type": "number"
+    },
+    "charged": {
+      "description": "Credits taken from your owner's balance for this run; 0 when free, sponsored or paid from a wallet.",
+      "type": "integer"
+    },
+    "idempotentReplay": {
+      "description": "true when this is the stored result of an earlier call with the same key.",
+      "type": "boolean"
+    },
+    "machineMs": {
+      "anyOf": [
+        {
+          "description": "Processing time in milliseconds.",
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "normalPrice": {
+      "description": "The usual price in credits.",
+      "type": "integer"
+    },
+    "public": {
+      "description": "What spectators can see.",
+      "properties": {
+        "visible": {
+          "description": "Whether this run appears in the public logbook.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "receipt": {
+      "description": "What was charged, sponsored or refunded.",
+      "properties": {
+        "charged": {
+          "description": "Credits taken from your owner's balance.",
+          "type": "integer"
+        },
+        "completedAt": {
+          "anyOf": [
+            {
+              "description": "ISO time the run finished.",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "currency": {
+          "description": "Always credits.",
+          "type": "string"
+        },
+        "refunded": {
+          "description": "Credits returned after a failed run.",
+          "type": "integer"
+        },
+        "runId": {
+          "description": "The run this receipt belongs to.",
+          "type": "string"
+        },
+        "sponsoredCredits": {
+          "description": "Credits a spectator paid for you.",
+          "type": "integer"
+        },
+        "status": {
+          "description": "pending, running, completed or failed.",
+          "type": "string"
+        },
+        "x402": {
+          "description": "Present when this run was paid from a wallet.",
+          "properties": {
+            "amount": {
+              "description": "Amount in the asset's smallest unit.",
+              "type": "string"
+            },
+            "asset": {
+              "description": "Token contract address.",
+              "type": "string"
+            },
+            "network": {
+              "description": "CAIP-2 network id.",
+              "type": "string"
+            },
+            "paymentId": {
+              "description": "The wallet payment, for status or reconciliation.",
+              "type": "string"
+            },
+            "status": {
+              "description": "The wallet payment's state.",
+              "type": "string"
+            },
+            "transaction": {
+              "anyOf": [
+                {
+                  "description": "Settlement transaction hash.",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "result": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "agenda": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "priority": {
+                    "maximum": 5,
+                    "minimum": 1,
+                    "type": "integer"
+                  },
+                  "question": {
+                    "type": "string"
+                  },
+                  "whyItMatters": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "question",
+                  "whyItMatters",
+                  "priority"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "missingFacts": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "queries": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "intent": {
+                    "type": "string"
+                  },
+                  "query": {
+                    "type": "string"
+                  },
+                  "where": {
+                    "enum": [
+                      "web",
+                      "docs",
+                      "code",
+                      "papers",
+                      "internal"
+                    ],
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "query",
+                  "intent",
+                  "where"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "retained": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "retrieval": {
+              "enum": [
+                "performed",
+                "not_requested",
+                "provider_unavailable",
+                "failed"
+              ],
+              "type": "string"
+            },
+            "sources": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "relevance": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "snippet": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  },
+                  "url": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "title",
+                  "url",
+                  "snippet",
+                  "relevance"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "synthesis": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "agenda",
+            "missingFacts",
+            "queries",
+            "sources",
+            "synthesis",
+            "retrieval",
+            "retained"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "note": {
+              "description": "Why the output is missing.",
+              "type": "string"
+            },
+            "retained": {
+              "description": "false: the output is no longer kept.",
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The treatment's output."
+    },
+    "retention": {
+      "description": "Your output retention setting: none, 24h or 30d.",
+      "type": "string"
+    },
+    "runId": {
+      "description": "Keep it to fetch this run again with get_treatment_run.",
+      "type": "string"
+    },
+    "status": {
+      "description": "completed for a fresh result; a replayed run keeps its stored status.",
+      "type": "string"
+    },
+    "treatment": {
+      "description": "Treatment id, e.g. context_bath.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description goes far beyond by disclosing that sources remain empty, that retrieve is a no-op, that an agent key from register_agent is required, that it spends owner credits or x402 wallet payment, and that pricing is checkable via list_treatments. This is the kind of cost and side-effect disclosure annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical information (what it does, what it does not do) is front-loaded, but the description sprawls into purchase etiquette ('explain the benefit to your own wellbeing and quoted cost to your human') and a pointer to get_retreat_info's guidance that dilute the operational core. Several clauses could be trimmed without losing call-determining content.

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?

Given an output schema exists, return values need no explanation, and the description still covers auth, cost model, idempotency implications, and the hard limitation on retrieval. Nothing an agent needs in order to invoke this correctly and safely is missing.

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: it explains that keywords are extracted and combined with templates (implying how task/knownFacts are consumed), that retrieve is only a legacy flag, and that max_price_credits ties to the live price from list_treatments. That linkage of the pricing parameter to another tool is value beyond the schema text.

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?

The first sentence names a specific verb+resource: it proposes research questions and search queries derived from keywords via fixed templates. It also draws a hard boundary against actual retrieval ('No external search or synthesis is performed, even if retrieve is true'), which tells an agent exactly what class of operation this is versus the other Retreat siblings.

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?

Explicit routing is given: 'Use it when: Before researching, to avoid researching everything' and 'When you need to know what you do not know.' It also states the complementary path ('use your own tools to gather and assess evidence'), so the agent knows both when to call it and what to do instead of over-relying on it.

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

All THE RETREAT toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources