Skip to main content
Glama

Zeno

by ch.zeno-works
OverviewDiscussionsAdmin

collect_api_key

Collect the key once the user has approved.

status is one of:

  • pending — nobody has approved yet, or (with throttled: true) we were rate-limited and learned nothing. Wait poll_interval_seconds, then call again — every answer carries it. Do not ask the user to tell you when they are done: you cannot detect it any other way, and handing the wait back to the user is how these sessions die.

  • ready — api_key is the credential. Follow the note that comes with it before anything else: the key does nothing until the client's configuration holds it, and calling again issues nothing. scope says what it can reach (onboarding, company or full) and company_id which company, if any. When scope is onboarding the user has no company yet and this key exists to make one: call onboarding_guide next — it needs no key, so read it while the user installs this one. It is the only place that says which documents to ask them for, and asking for them all at once is the difference between one conversation and seven.

  • collected — this request already issued its key and nothing new was issued. Follow the note.

  • denied — stop. Do not start another request; a human refused it ("that was not me"). Raising a second one is how a refusal turns into a prompt the user has to refuse repeatedly.

  • expired — the request timed out. Do not simply open another one, and what to do depends on which door you opened, which only you know. request_api_key: ask whether they saw the approval page, and call it again if they want to retry. start_signup: they may have finished registering in the browser meanwhile, in which case they now HAVE an account and request_api_key is the path — ask. If they did not, tell them plainly that it timed out; starting another signup without asking is how a refusal turns into a prompt they have to refuse repeatedly.

A pending answer is a success, not an error; it is deliberately not an error status, because an error would be read as "do not retry" and retrying is the entire protocol. A rate limit mid-wait is reported the same way, with throttled: true and a longer poll_interval_seconds — slow down, do not stop.

Input Schema

NameRequiredDescriptionDefault
claim_tokenYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses that pending is deliberately not an error because errors read as 'do not retry', that collected means idempotently nothing new was issued, that api_key must be installed via the accompanying note before it works, and that scope governs reach. It also surfaces the rate-limit-becomes-throttled behavior and the longer poll interval.

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

Conciseness4/5

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

Front-loaded with purpose and organized as a scannable status list, which is the right shape for a state machine. It is dense but mostly earns its length, with only mild repetition in the denied/expired branches about refusals turning into repeated prompts.

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

Completeness4/5

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

No output schema exists, so the description must define the return contract, and it does thoroughly: the full status enum, the presence of api_key, note, scope, company_id, throttled, and poll_interval_seconds. What is missing is the provenance of claim_token and any stated default for poll_interval_seconds.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single input parameter, claim_token, has 0% schema description coverage and is never mentioned in the description — its origin and format are unexplained. The description details output fields (status, api_key, note, scope, company_id, throttled, poll_interval_seconds) but that does not compensate for the undocumented required input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Collect the key') plus the precondition ('once the user has approved'), so an agent knows this is the polling/retrieval half of the key flow. It references request_api_key, start_signup, and onboarding_guide in the status branches, giving implicit sibling differentiation, but the opening sentence alone does not explicitly distinguish this tool from the two ways a claim is created.

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?

It gives explicit when-to-call guidance (only after approval), a per-status action map, named alternatives, and explicit prohibitions ('denied — stop', 'do not simply open another one'). The retry protocol, including the throttle backoff, is spelled out rather than left to inference.

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

All Zeno toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources