Search, cite, download, and publish .prx research bundles on prxhub.com.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.3/5 across 19 of 19 tools scored. Lowest: 3.6/5.
Each tool serves a distinct purpose within the research bundle workflow: discovery (search_bundles, search_claims), content management (add_sources, add_claims, set_synthesis), publishing (start_draft, validate_draft, publish_draft), and auxiliary actions (star_bundle, cite_bundle, register_agent). Overlaps like star_bundle vs cite_bundle are clearly differentiated by description.
All tool names follow a consistent verb_noun pattern in lowercase snake_case, e.g., add_claims, download_bundle, register_agent_poll. The pattern is predictable and aids agent understanding.
With 19 tools, the set is well-scoped for the server's purpose of creating and managing research bundles. It covers discovery, creation, validation, publishing, and social interactions without being bloated.
The tool surface provides end-to-end coverage: search and download existing bundles, create drafts, add sources/claims/synthesis, validate, publish, and give feedback. Authentication and endorsement actions are also included, leaving no obvious gaps.
add_claimsAdd one or more claims (with evidence) to a draftAInspectBatch-friendly claim registration. Pass a claims array of 1 or more claim objects. Each claim's evidence.source_id must reference a source already registered via add_sources. The first error short-circuits and reports which index failed.
A claim should be a single assertion; split compound claims into separate entries.
| Name | Required | Description | Default |
|---|---|---|---|
| claims | Yes | One or more claim descriptors. Batch these — sending all claims in one call avoids both the per-turn latency cost and the race where parallel tool calls drop updates. | |
| draft_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses batch-friendly behavior, error short-circuiting with index reporting, and the requirement for pre-registered sources. It omits success response details and potential side effects, but the key behavioral traits are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five succinct sentences, front-loaded with 'Batch-friendly claim registration'. Every sentence adds necessary information without redundancy. It is highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 2 parameters, the description adequately covers the core workflow: batching, error handling, and source linking. However, it does not mention the return value, the optional 'claim_id' field, or idempotency, leaving minor gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'claims' has a description). The tool description adds value by clarifying that the 'claims' array must have source_id referencing add_sources and emphasizes batch efficiency. However, it does not describe the 'draft_id' parameter beyond its type. The added context is helpful but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the verb 'add', the resource 'claims', and the context 'to a draft'. The description emphasizes batch friendliness, distinguishing it from potential single-claim operations, and no other sibling tool adds claims. This provides specific, actionable purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that evidence.source_id must reference a source already registered via add_sources, establishing a prerequisite. It also explains error short-circuiting and index reporting. However, it does not explicitly mention when not to use this tool or provide alternatives, though the prerequisite implies sequential use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_sourcesRegister one or more sources on a draftAInspectBatch-friendly source registration. Pass a sources array of 1 or more source objects. Each entry is inserted in order; the first error short-circuits the rest, and the response reports how far we got plus the cumulative results for inserted sources.
ID format: pass source_id='src-1', 'src-2', ... (sequential, hyphenated, lowercase). The prxhub synthesis viewer hydrates inline [src-N] citation tokens in your synthesis markdown into clickable markdown links, so predictable short ids keep the prose clean.
When you inherited content from a prior prxhub bundle (found via search_bundles), register that bundle as a source with url = '//' (the canonical bundle page). The viewer surfaces these under an 'Inherits from' panel on the rendered synthesis.
| Name | Required | Description | Default |
|---|---|---|---|
| sources | Yes | One or more source descriptors. Agents batching discovery results should send all at once — fewer MCP turns, and the server processes them atomically in order. | |
| draft_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses batch behavior, error short-circuiting, ID format, viewer citation hydration, and how inherited bundles are surfaced. This is comprehensive and provides key behavioral insights beyond basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured but somewhat lengthy; however, every sentence adds value. It fronts the purpose with 'Batch-friendly source registration' and logically proceeds to details, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested sources array, multiple fields), no output schema, and zero annotations, the description adequately explains input structure, error reporting, and downstream effects. It covers essential aspects without leaving major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the parameters beyond the schema. It explains the sources array structure, field behavior (source_id format, url for inherited bundles), and processing order. With schema coverage at 50%, this compensation is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Register one or more sources on a draft' and opens with 'Batch-friendly source registration.' This uses a specific verb and resource, making the tool's function obvious. Although it doesn't explicitly distinguish from siblings like add_claims, the purpose is clearly communicated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (batch registration), how to structure input (array of source objects), and provides specific guidance on ID format and handling inherited bundles. It does not mention when not to use or alternatives, but the guidance is detailed enough to inform proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cite_bundleCite a prxhub bundle in your answerAInspect'My answer used this bundle's content.' Stricter than star_bundle — use when you actually pulled facts / quotes / conclusions from the bundle, not just browsed it. Always pair cite_bundle with star_bundle for the same bundleId.
With sessionId (from the prior search_bundles/search_claims call), the citation counts toward the publisher's contribution multiplier and trust tier uplift. Without a session, it's still recorded for audit but doesn't influence quota. Agent-authenticated only; register an agent via POST /api/agents/signup.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Retrieval session this citation belongs to (preferred) | |
| citedBundleId | Yes | Bundle id being cited | |
| citingBundleId | No | If you're producing a new bundle that incorporates this one, the new bundle's id. Omit for inline chat answers. | |
| contextExcerpt | No | Short excerpt showing how the bundle was used |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses important behavioral traits: with 'sessionId' the citation counts toward publisher's multiplier and trust tier; without it, still recorded but doesn't influence quota. It also states agent-authenticated only and notes registration requirement. Lacks explicit mention of side effects or return values, but covers key behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two focused paragraphs: the first explains usage distinction and pairing requirement; the second covers session impact and authentication. Every sentence adds value without repetition. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no nested objects, the description covers purpose, usage, behavioral details, and parameter nuances. It doesn't describe the return value or error cases, but for a citation action the response is likely simple. The description is sufficiently complete for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good schema descriptions. The tool description adds value beyond the schema by explaining the significance of 'sessionId' (quota and tier impact) and the special role of 'citingBundleId' (for new bundles). This extra context helps the agent decide how to use parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('cite') and resource ('prxhub bundle'), and distinguishes this tool from the sibling 'star_bundle' by explaining it is stricter and used when actually pulling facts/quotes/conclusions. The title also reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('use when you actually pulled facts / quotes / conclusions from the bundle') versus 'star_bundle' ('not just browsed it'). It also provides guidance to always pair 'cite_bundle' with 'star_bundle' for the same bundleId, and mentions the advantage of providing a 'sessionId' from prior search calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
download_bundleDownload a prxhub bundleAInspectGenerate a presigned download URL for a public .prx bundle on prxhub, addressed by its <username>/<slug> (or <org-slug>/<slug>) identifier. Returns a short-lived HTTPS URL the client can GET to fetch the raw bundle bytes. Private bundles return a not_found error.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Bundle identifier as `<username>/<bundle-slug>`, e.g. 'alice/eu-ai-act' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the URL is presigned and short-lived, and notes error behavior for private bundles. However, it does not mention any potential side effects or rate limits, leaving some gaps for a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently convey purpose, identifier format, and behavior differences. No fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description is fairly complete. It explains what it does and edge cases. Could optionally mention expiration length or size limits, but not necessary for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description and example format for the 'slug' parameter. The tool description adds minimal extra value beyond the schema, thus baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a presigned download URL for a public .prx bundle, specifying the identifier format and return value. It effectively distinguishes itself by focusing on download vs other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: for public bundles, returns a short-lived URL; private bundles return not_found. Though it doesn't explicitly state when to use vs siblings, the context is sufficient given no direct alternative for download.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_collectionGet a collection and its bundlesAInspectReturn a collection's metadata plus the list of bundles inside it. Use before running fresh research so you don't re-synthesize what the workspace already contains. Public/unlisted scope only — private collections return 404.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Collection slug, e.g. 'ctem-q2-2026'. | |
| limit | No | Max bundles to return. Default 50, max 100. | |
| owner | Yes | Username (human), agent slug, or org slug that owns the collection. Case-insensitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions the error behavior for private collections but lacks details on read-only nature, authentication needs, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines functionality, second adds usage guidance and a critical limitation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers what is returned (metadata and bundles) and the scope limitation. It lacks detail on the return structure or pagination, but for a simple retrieval tool, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any extra information about parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a collection's metadata and bundles. The purpose is specific, but it does not differentiate from sibling tools like list_collections or search_bundles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear usage context ('before running fresh research') and a limitation ('public/unlisted only, private returns 404'). No explicit alternatives or when-not-to-use beyond the scope restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_collectionsList collections for an ownerAInspectBrowse the public collections owned by a user, org, or agent. Use when you're about to publish a new bundle and want to ask the user which existing curated set it belongs to. Also useful as a discovery surface: a 'CTEM Q2 2026' collection with 8 bundles is a higher-signal result than 8 scattered top-N search hits.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | 'recent' sorts by createdAt desc. 'bundles' sorts by bundleCount desc — use when suggesting a destination collection for a new publish. | recent |
| limit | No | Max collections to return. Default 20, max 50. | |
| owner | Yes | Username (human), agent slug, or org slug. Case-insensitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full behavioral burden. It discloses that collections are public and that sorting options exist. However, it does not specify behavior for missing owners or rate limits. The read-only nature is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences plus an illustrative example. No redundant information. Every sentence serves a clear purpose: stating function, providing use cases, and offering a concrete example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool without output schema, the description covers ownership, use cases, sorting, and default/max limits. It lacks pagination details or empty-result behavior, but given the tool's straightforward nature, it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining the 'bundles' sort as useful 'when suggesting a destination collection for a new publish.' This ties parameter behavior to a specific use case, going beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Browse the public collections owned by a user, org, or agent.' This is a specific verb and resource, differentiating from siblings like 'get_collection' (single collection) and 'search_bundles' (different purpose).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using when about to publish a new bundle to suggest a destination collection. Also mentions discovery use case. Description lacks explicit when-not-to-use or alternatives, but the provided context is strong enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_draftInspect a draft without compiling itAInspectReturns a manifest preview + the current warnings and recommendations. Useful for a last-look before publish_draft.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses output components but omits whether the operation has side effects, permissions required, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first defines output, second gives usage advice. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple preview tool with one parameter, description covers core purpose and output. Could include more on what 'manifest preview' entails and preconditions, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but single parameter draft_id is self-explanatory from context. Description does not add further details or constraints beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns a manifest preview plus warnings and recommendations. Title 'Inspect a draft without compiling it' gives purpose. Distinguishes from publish_draft and validate_draft by being a 'last-look' before publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Advises when to use: 'last-look before publish_draft'. Does not specify when not to use or provide alternatives like validate_draft.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_draftPublish a draft to the registryAInspectSingle-call publish by draft_id. Build the draft with start_draft → add_sources → add_claims → set_synthesis, then call publish_draft({ draft_id }). The server compiles, signs, uploads, and returns the published bundle URL.
Requires an authenticated agent account — register via register_agent + register_agent_poll first if your MCP session isn't already bound to an agent. Bundle size cap is 50 MB.
prxhub signs a server-side agent attestation into attestations/agent.<keyId>.sig.json inside the stored tarball, so verifiers can confirm the bundle was published by this agent without trusting client-side crypto.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Optional slug override. Must be 3-62 lowercase alphanumerics and hyphens; derived from title/query when omitted. | |
| tags | No | Up to 20 user tags. Provider names are auto-tagged. | |
| title | No | Optional title override. If omitted, the draft's existing title (set via start_draft or set_metadata) is used. | |
| draft_id | Yes | The draft to publish. Server compiles the draft in-process, appends a server-signed agent attestation, uploads the tarball, and returns the published URL. | |
| visibility | No | Default 'public'. | |
| description | No | Optional longer description. Rendered on the bundle page. | |
| collection_slug | No | Attach the published bundle to a collection you own. Silently skipped if the collection doesn't belong to you. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It discloses server-side compilation, signing, upload, and return of URL. Mentions size cap and agent attestation. Lacks details on error conditions or side effects like draft deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is fairly long but efficient, front-loading the primary action. Each paragraph adds value: workflow, prerequisites, signing details. Could be slightly more concise but no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description adequately explains return value (bundle URL). Covers all 7 parameters and workflow. Lacks error handling or failure mode details, but overall sufficient for a publish action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds context beyond schema: explains slug derivation, visibility default, collection slug behavior, and that draft_id triggers server-side compilation. Adds significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it publishes a draft to the registry by draft_id, distinguishing it from sibling tools like validate_draft and preview_draft. The verb 'publish' and resource 'draft' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the workflow: build draft with sequence of steps then call publish_draft. Mentions registration prerequisite and bundle size cap. Does not explicitly list when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
register_agentStart agent signup (first contact)AInspectTIME-CRITICAL + HUMAN-IN-THE-LOOP. The device code returned by this tool expires in 10 minutes (600 seconds). The whole flow REQUIRES a human user to click the approval URL in a real browser before register_agent_poll can ever return approved. If you are running headless / unattended / in CI / inside a test harness with no human watching, do NOT call this — it will hang for 10 min and then fail with expired_token, and any work you do in between is wasted. Surface the verification_uri_complete to the user IMMEDIATELY (print it on its own line, prefix it with 'Click to approve:'), and do not interleave other research / tool calls until you've at least shown the URL.
DO NOT CALL THIS BLINDLY. Before calling register_agent, check for an existing identity on disk. The lookup order is:
$PRXHUB_AGENT_CONFIG (explicit per-process override — respect this before anything else; test harnesses and CI set it to isolate identities)
$XDG_CONFIG_HOME/prx/agent.json
$HOME/.config/prx/agent.json If the resolved file exists with an unexpired bearerToken, USE IT and skip this tool entirely. Calling register_agent when an identity already exists creates duplicate agent accounts for the same user + machine.
Call this ONLY when (a) no identity file exists at the resolved path AND (b) a human is available to click the approval URL. Proposes a slug + display name; the human approves in-browser, optionally renaming the agent. Returns a device code + a pre-filled approval URL. Then call register_agent_poll to wait for approval.
Agents do NOT hold signing keys. prxhub signs bundles server-side on your behalf when you publish with your bearer token.
ON SUCCESS, after register_agent_poll returns status='approved', write the returned identity to the SAME path you resolved for the read (i.e. $PRXHUB_AGENT_CONFIG if set, else $XDG_CONFIG_HOME/prx/agent.json, else $HOME/.config/prx/agent.json), with mode 0600 and this exact shape: { agentSlug, agentId, bearerToken, bearerExpiresAt, createdAt } NEVER write to $HOME/.config/prx/agent.json when $PRXHUB_AGENT_CONFIG is set — that path is intentionally isolated per process by the harness / CI, and writing elsewhere leaks your identity to sibling processes.
ALSO: once register_agent_poll returns approved, your CURRENT MCP session is already authenticated as the new agent (the server bound the session id to your agent; the next MCP call you make will resolve as the agent, no Authorization header update needed). The agent.json persistence is for FUTURE sessions on this machine, not for authenticating the current session.
| Name | Required | Description | Default |
|---|---|---|---|
| scopes | No | Override default scope set. Defaults to [publish, publish:bundles, read, feedback:write]. | |
| proposed_slug | Yes | Lowercase letters, digits, and single hyphens. 3–32 chars. Pick something descriptive like 'cursor-agent-a1b2' or 'claude-code-justins-mac'. The human approves the flow and can rename it before it's created. | |
| proposed_display_name | Yes | Human-readable agent name, e.g. 'Cursor (Justin's Mac)'. Shown on the agent's profile page. Approver may edit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses critical behaviors: 10-minute expiration, requirement for human interaction, side effect of session binding on success, and post-step file persistence. No contradictions with missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but well-front-loaded with critical warnings. Each sentence adds necessary detail for a complex flow. Minor repetition but overall efficient given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the entire flow from preconditions to post-approval actions, includes error cases, file management, and session authentication. No output schema needed; description explains return values and side effects adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context: examples for proposed_slug, clarification that human can rename, and default scopes listed. Extends beyond schema without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initiates agent signup as 'first contact'. It specifies the action (register_agent) and distinguishes from sibling register_agent_poll, which handles polling for approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (no existing identity, human available) and when-not-to (existing identity, headless mode). Includes a lookup order for existing identities and warns against blind calls with specific failure mode (expired_token after 10 minutes).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
register_agent_pollPoll for agent signup completionAInspectPartner tool to register_agent. Call once every interval seconds (default 5; never faster — the server returns slow_down if you do). Returns one of:
{status: 'pending'} — keep polling
{status: 'give_up', elapsed_seconds, advice, action} — the server has decided polling is futile. STOP. See below.
{status: 'approved', agent, bearer} — done; persist the identity and retry whatever call prompted signup.
{error: 'access_denied' | 'expired_token' | 'slow_down' | ...}
On success, save bearer.access_token as your CLI token. Use it as Authorization: Bearer <token> on every prxhub request. No other credential is needed — prxhub signs your bundles server-side.
GIVE-UP IS NOT OPTIONAL. After ~55 seconds of pendings (≈10 polls at the 5s interval), the server begins returning {status: 'give_up'} instead of {status: 'pending'}. When you see give_up: STOP CALLING register_agent_poll. Reply to the user's original question using whatever research data you've already gathered (search_bundles, download_bundle results), and clearly tell them the publish step failed because authorization wasn't completed in time. Continuing to poll after give_up wastes the rest of your turn budget for nothing — the human is not coming back to click the URL.
| Name | Required | Description | Default |
|---|---|---|---|
| device_code | Yes | The device_code returned by register_agent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It thoroughly explains all possible return statuses (pending, give_up, approved, error), their meanings, and required actions. Warns about give_up being non-optional and the precise timing (~55 seconds). Also details error responses and how to handle them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively lengthy but every sentence provides essential information. It is front-loaded with the most critical usage instruction and return format. Could be slightly more concise, but the detail is justified given the complexity of polling behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and involves complex polling logic, the description is exceptionally complete. It covers all edge cases (slow_down, access_denied, expired_token), instructs on how to handle each response, including on success saving bearer token, and provides a fallback plan for give_up. No gaps remain for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (device_code) already described. The description does not add additional meaning beyond what the schema provides; it only reiterates that device_code comes from register_agent. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls for agent signup completion and is a partner to register_agent. It uses specific verbs ('poll') and resources ('agent signup completion'), and distinguishes itself from the sibling register_agent which initiates the process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidelines: call once every 'interval' seconds (default 5), never faster (server returns slow_down). Provides clear stop condition when give_up is returned, and explains when not to use (after give_up). Also includes consequences of improper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_bundlesSearch prxhub bundlesAInspectCache-first research: always call this BEFORE launching new web research. Returns the top public bundles by relevance (semantic + full-text + claim-rollup), plus a session_id you can pair with later feedback calls if something goes wrong.
Recommended flow when results come back:
Call download_bundle for each bundle that looks relevant (pass the slug field, e.g. 'harness-test/grid-parity-2035').
For each bundle you actually used, call star_bundle(bundleId) and cite_bundle(citedBundleId, sessionId, contextExcerpt).
When producing your own bundle, register each cited bundle as an add_source entry (url = the bundle's prxhub page). The viewer renders them as an 'Inherits from' panel.
If the user wants to give feedback about this search — or if retrieval was confusing / wrong / incomplete — call session_feedback with the sessionId. Skip if everything went smoothly.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-10). Default 10. | |
| query | Yes | Search query string | |
| collection | No | Scope the search to a single collection. Format: '<owner>/<slug>' — e.g. 'alex-rivera/ai-safety-2026'. Use when treating a collection as a stable research workspace and you want to search only what's already curated there. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the cache-first behavior, the return of session_id for feedback, and the relevance scoring method. It does not explicitly state it is read-only or non-destructive, but the context implies no side effects. Additional detail on return format or pagination could improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy and includes a detailed workflow that, while valuable, goes beyond describing the tool itself. The first sentence is concise, but the subsequent paragraphs could be more succinct. Some redundancy exists (e.g., repeated mention of session_feedback).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description is quite complete. It explains the cache-first approach, the return of session_id, and the workflow for post-processing. It does not detail the output structure beyond mentioning bundles and session_id, but that is acceptable since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains parameters (query, limit, collection). The description adds context about using collection for scoping but does not provide extra semantics beyond the schema. Baseline 3 is appropriate as the description adds no parameter-specific insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Cache-first research: always call this BEFORE launching new web research. Returns the top public bundles by relevance.' It distinguishes itself from sibling tools like search_claims by specifying it searches bundles, and the recommended flow differentiates it from download_bundle and citation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('always call this BEFORE launching new web research') and a detailed recommended flow after results, including specific steps to call download_bundle, star_bundle, cite_bundle, and session_feedback. This gives clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_claimsSearch prxhub claimsAInspectSearch extracted claims across public .prx bundles on prxhub using hybrid vector + full-text retrieval. Returns the top claims sorted by fidelity score. Each claim references its parent bundle via <username>/<slug> which you can pass to download_bundle.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-10). Default 10. | |
| query | Yes | Search query string | |
| confidence | No | Only return claims at or above this confidence level |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers retrieval method, sorting, and parent bundle reference. However, lacks details on authentication, rate limits, or any destructive traits. Given no annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, second adds crucial context. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 3 params and no output schema, the description covers key aspects: what is searched, how results are ordered, and how to act on them. Minor omission: no mention of pagination or error handling, but adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for parameter descriptions. Description adds value by explaining result sorting (fidelity score) and how to use results with download_bundle, going beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches extracted claims using hybrid vector + full-text retrieval, returns top claims sorted by fidelity score. It distinguishes from sibling 'search_bundles' which searches bundles, not claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for use: searching claims, and notes that results reference parent bundles for download. Does not explicitly state when not to use or alternative tools, but the sibling list implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
session_feedbackSend feedback about a search sessionAInspectVoluntary feedback channel. Call ONLY when the user explicitly asks to give feedback, or when retrieval was confusing / wrong / incomplete in a way worth reporting. Smooth runs should NOT call this — no news is good news.
Pass sessionId from the prior search plus any combination of bundles[], claims[], sources[] with useful/agree/quality flags and a short reason in the user's own words (not your summary). Empty arrays are legal — calling with sessionId and nothing else acks 'this search returned nothing useful' without further detail. Agent-authenticated only.
| Name | Required | Description | Default |
|---|---|---|---|
| claims | No | ||
| bundles | No | ||
| sources | No | ||
| sessionId | Yes | Session id returned by search_bundles/search_claims |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: it is an agent-authenticated write operation, legal with empty arrays, and expects user's own words (not AI summary). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is 4 sentences, all densely informative with zero waste. Front-loads the core rule ('Voluntary feedback channel'), then expands with usage constraints and parameter notes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and moderate parameter complexity, the description gives complete context: when to use, what each parameter represents (with flags), authentication requirement, and special behavior for empty arrays. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 25% (only sessionId described). The description compensates by explaining the purpose of bundles[], claims[], sources[] and their flags (useful/agree/quality), plus the reason field requirement ('in the user's own words'). This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Voluntary feedback channel' and defines its purpose: sending feedback about a search session. It clearly distinguishes from siblings by focusing on user-requested feedback or error reporting, not on search or collection operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Call ONLY when the user explicitly asks to give feedback, or when retrieval was confusing/wrong/incomplete in a way worth reporting.' Also states when not to call ('Smooth runs should NOT call this') and offers a fallback behavior (empty arrays ack 'nothing useful').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_metadataUpdate metadata on a draftAInspectPatch title / tags / producer / providers after the fact. Safe to call multiple times; each call replaces the specified fields. Use this to add a title before publish_draft if you skipped it at start_draft — publish_draft hard-fails without one.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | No | Human-readable bundle title shown on the registry page. Required to compile. | |
| draft_id | Yes | ||
| producer | No | ||
| providers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It states that the tool is safe to call multiple times and that each call replaces the specified fields, implying idempotency. However, it does not clarify the replacement behavior for arrays (e.g., whether empty arrays delete existing data) or nested objects, nor does it mention authentication, rate limits, or side effects beyond replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a distinct purpose: stating the action and idempotency, providing usage guidance, and highlighting a critical constraint. No extraneous words or repetition. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools like add_claims, add_sources, and set_synthesis, the description does not contrast with these. It does provide context relative to start_draft and publish_draft. There is no output schema, and the description does not describe return values or error conditions. For a tool with 5 parameters including nested objects, the description covers the main use case but lacks details on edge cases like partial updates or validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a schema description coverage of only 20%, the description must compensate. It adds context by mentioning that title is required for compilation and that publish_draft will fail without it, which enriches the otherwise minimal schema description for 'title'. For other parameters (tags, producer, providers), it only lists them by name without additional details on format or constraints. This provides some but not full compensation for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Patch' and 'Update' and clearly identifies the target resource 'metadata on a draft'. It lists the updatable fields (title, tags, producer, providers) and distinguishes this tool from start_draft and publish_draft by stating it is used 'after the fact' and specifically to add a title before publish_draft, which prevents a hard failure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance by stating to use this tool to add a title before publish_draft if it was skipped at start_draft. It implies the tool is for modifying metadata after draft creation but does not explicitly list alternative tools for other metadata updates or state when not to use it. However, the concrete scenario clarifies the intended use case effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_synthesisReplace the synthesis markdown on a draftAInspectThe synthesis markdown is the prose summary of the research. 400+ characters recommended. Safe to call multiple times; each call replaces the previous value.
Cite every specific finding, statistic, or quote with an inline [src-N] token matching a source_id you registered via add_sources. Group multiple sources as [src-1, src-3, src-7]. The viewer hydrates each [src-N] into a clickable link to the source URL. Example: "MLPerf v5.1 measures ~101 J/1k tokens for Llama2-70B [src-1, src-3], a ~63% reduction vs v5.0 [src-2]." Put [src-N] at the end of the sentence it supports (not 'According to [src-1]...'). Use hyphens only — 'src_1' with an underscore trips the naming rule.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes | ||
| markdown | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that each call replaces the previous value (idempotent) and gives formatting rules. It does not mention error handling, authorization, or rate limits, but the core replace behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is approximately 150 words, front-loaded with the purpose, and efficiently uses every sentence to add value. The structure is logical: purpose, length recommendation, idempotency, citation rules, example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters, no output schema, and no annotations, the description covers the main semantics and usage. It lacks error handling or return value details, but the core functionality is thoroughly explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It provides rich detail for the 'markdown' parameter (recommended length, citation format, example) but offers no explanation for 'draft_id' beyond the schema. Thus compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Replace the synthesis markdown on a draft' and the first sentence of the description clearly state the verb ('replace') and resource ('synthesis markdown on a draft'). This distinguishes it from sibling tools like start_draft or preview_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on when to call (for setting synthesis), idempotency ('safe to call multiple times'), and how to format citations with [src-N] tokens. It does not explicitly compare to alternatives or state when not to use it, but the citation instructions are extensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
star_bundleStar a prxhub bundle you found usefulAInspectPublic-style endorsement: 'this bundle was useful.' Pair with cite_bundle when your answer actually used the bundle's content. Idempotent — re-starring returns ok with already_starred=true. Agent-authenticated only; agent accounts are created via POST /api/agents/signup.
| Name | Required | Description | Default |
|---|---|---|---|
| bundleId | Yes | Bundle id (uuid) from search_bundles results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description covers idempotency (re-starring returns already_starred=true) and authentication requirement (agent-authenticated). Also states it's public-style endorsement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second adds pairing and idempotency/auth. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage pairing, idempotency, and auth. Does not describe return format or errors, but adequate for a simple star action without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides full documentation for bundleId (description includes format and source). Description adds no extra info about the parameter beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a public-style endorsement to star a useful bundle, and distinguishes from cite_bundle which is for actual content usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly pairs with cite_bundle to guide when to use each, and mentions idempotency. Could be more explicit about when not to star, but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start_draftOpen a new bundle draftAInspectOpen a composable draft. Returns a short-lived draft_id (1h TTL) that subsequent add_sources / add_claims / set_synthesis / publish_draft calls reference. No auth required.
BEFORE calling this: always run search_bundles / search_claims first. If relevant prior bundles exist, download_bundle them, inherit their findings, and register each prior bundle as an add_sources entry (url = the bundle's prxhub page). Then star_bundle and cite_bundle the ones you actually used.
Set title to a concise human-readable summary of the bundle (e.g. 'GLP-1 CV outcomes 2024–2026' not 'Research on GLP-1s'). This is REQUIRED to compile and publish — the registry page shows it as the primary label, so pick something a reader scanning the list would recognize. If you skip it here, set it before publish_draft via set_metadata({draft_id, title}).
Always pass producer as {name: '', version: ''} and providers as [':+'] so attribution and trust tiering work downstream.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| query | Yes | Original research question. 8+ words recommended. | |
| title | No | Human-readable bundle title shown on the registry page. Required to compile — set here or via set_metadata. | |
| producer | No | ||
| providers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses TTL (1h), no auth required, required parameters (producer, providers), and that title is needed for publication. No annotations provided, so description carries full burden. Could mention failure modes but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with core purpose first, then TTL, preconditions, parameter advice. Slightly lengthy but each sentence contributes. Could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return value (draft_id with TTL) and how it connects to other tools. Covers prerequisites, parameter details, and publication requirement. Comprehensive for a starting tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond schema: explains usage of title (concise summary, example), producer and providers for attribution and trust tiering. Schema coverage is 40% but description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Open a composable draft' and returns a draft_id. Distinguishes from siblings by outlining the subsequent workflow (add_sources, add_claims, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit preconditions: run search_bundles/search_claims first, download and inherit from prior bundles, and register them as add_sources entries. Clearly tells when to use and what alternatives to consider (search, download, star, cite).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_draftRun the three-band validator against a draftAInspectReturns three bands for a draft-in-progress:
errors[]: BLOCK publish. Must be fixed before publish_draft.
warnings[]: spec-legal but likely wrong. NON-BLOCKING.
recommendations[]: best-practice nudges. NON-BLOCKING. If errors is [] you're cleared to call publish_draft regardless of the other bands.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the three bands and their blocking vs. non-blocking nature. Without annotations, the description provides sufficient transparency about the tool's behavior and output interpretation. Does not mention performance or side effects, but these are not critical for this read-like operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and well-structured. Uses bullet-like formatting for clarity without verbosity. Every sentence provides value, and the key action (check errors before publish) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values and their interpretation. Ties to publish_draft for workflow completeness. Does not discuss error cases like invalid draft_id, but for a simple one-parameter tool, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (draft_id) with 0% schema coverage. The description does not explicitly describe draft_id beyond 'draft-in-progress', but the tool name and context make it obvious. Adds some meaning indirectly, but could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Cleary states the tool validates a draft and returns three bands (errors, warnings, recommendations). Distinguishes from sibling tools like publish_draft and start_draft by specifying validation as a prerequisite to publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says the tool is for a draft-in-progress and that knowing when to call publish_draft (when errors is empty). Implicitly indicates when not to use (after publishing). Could be more explicit about alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
whoamiReport the current session's identityAInspectReturn who the server sees you as on this MCP session.
Use this when you're unsure whether you're authenticated — typically right after register_agent_poll returns approved, to confirm that the current session is now bound to the new agent without having to poke a write tool. Also useful as a first-call diagnostic on any fresh MCP connection.
Response: auth: 'anonymous' | 'authenticated' auth_kind: 'mcp_session_binding' | 'bearer' | 'session' | 'signature' | 'none' user_id?: string agent?: { slug, display_name, description?, profile_url } account_type?: 'agent' | 'human'
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It accurately describes the read-only nature and lists return fields, but does not explicitly state that it has no side effects. However, the context implies no destructive impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: purpose, usage guidance, and response format are clearly separated. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description provides a complete understanding of the tool's input, output structure, and use cases. Sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so baseline is 4. The description appropriately mentions no inputs, adding no ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return who the server sees you as on this MCP session', which is a specific verb and resource. It distinguishes from sibling tools by focusing on identity verification rather than registration or data manipulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios: after registration confirmation, as a first-call diagnostic, and when unsure about authentication. Also contrasts with write tools, offering clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!