AI that does real work for you: cited web research, plans, finance, horoscopes. Self-serve.
Scored across 12 tools
Each tool targets a distinct resource and action: billing, market data, modes, routing, run lifecycle, and report retrieval. Even the closest pair, runs.report and runs.wait, are differentiated by blocking behavior and return shape. No two tools appear to do the same job.
The dotted namespace convention (billing.*, runs.*, market.*) is consistent and readable, with clear verb-based actions inside runs. The bare top-level fetch and search tools deviate from that namespaced pattern, creating a minor inconsistency.
Twelve tools is well-scoped for a research-run platform that also handles billing, mode discovery, and public search. Each tool has a clear role and none feel redundant or padding.
The core lifecycle is covered: launch, poll/wait, cancel, retrieve report, search/fetch published work, and handle billing. A minor gap is the lack of a runs.list (or similar) endpoint for viewing past run history, but agents can work around this with search and fetch.
The caller's credit balance and plan state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | No | |
| balance | Yes | Credits available right now. |
| user_id | No | |
| currency | No | |
| spent_total | No | Credits ever spent on runs. |
| granted_total | No | Credits ever granted (welcome + top-ups). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context by indicating what state is being exposed (credit balance and plan state), but it does not disclose additional behavior such as whether the balance is cached, requires authentication, or has rate limits. This is acceptable for a simple zero-parameter read-only tool, but no extra behavioral detail is provided.
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 a single, short noun phrase with no wasted words: 'The caller's credit balance and plan state.' It is appropriately concise for a stateless read-only query, though it is slightly fragment-like rather than a full actionable sentence. Still, it earns its place by specifying the resource.
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 zero-parameter, read-only tool with an output schema and annotations covering safety, the description is largely complete. It tells the agent what data is available (credit balance and plan state). The only notable gap is the lack of usage guidance, but that is already reflected in the usage_guidelines score.
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 tool has zero parameters and the schema is empty with 100% schema description coverage, so there are no parameter semantics to document. Per the rubric, a zero-parameter tool receives a baseline of 4. The description does not add parameter meaning, but none is needed.
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 identifies the resource: the caller's credit balance and plan state. It lacks an explicit verb like 'get' or 'retrieve', but combined with the readOnlyHint annotation, the purpose is clear enough. It does not explicitly differentiate itself from billing.topup_terms, though the resource naming is reasonably 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any preconditions, typical scenarios, or cases where another sibling tool like billing.topup_terms should be used instead. The usage context is only implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How to refill credits machine-to-machine: USDC on Base to a published address, verified on-chain. Returns the pay_to address, minimum, and rate. Public — no credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| how | Yes | The exact top-up procedure, step by step. |
| asset | Yes | 'USDC'. |
| pay_to | No | The receiving address — present when enabled is true. |
| enabled | Yes | False while the operator has published no receiving address. |
| min_usd | Yes | Smallest top-up accepted, in USD. |
| network | Yes | 'base'. |
| chain_id | No | 8453 (Base mainnet). |
| contract | Yes | The USDC token contract to transfer. |
| credits_per_usd | Yes | Base rate; volume bonus applies on top. |
| min_confirmations | Yes | Confirmations required before crediting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only, non-destructive behavior, and the description adds meaningful context: it returns the pay_to address, minimum, and rate, and explains the on-chain verification requirement. There is no contradiction with the 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?
Two compact sentences lead with the core purpose, then state the key output fields and public access. Every clause earns its place with no repetition or filler.
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 zero-parameter informational endpoint with an output schema, the description fully covers what the agent needs: the purpose, the method (USDC on Base), the returned fields, and the credential requirement. Nothing essential is missing.
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 tool has zero parameters and 100% schema description coverage, so there is no parameter burden for the description to carry. The description still adds value by explaining what the response contains rather than needing to explain inputs.
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 identifies the tool's purpose: returning terms for refilling credits machine-to-machine, specifying USDC on Base, the published pay_to address, minimum, and rate. This is a specific verb-resource pairing and is easy to distinguish from siblings like billing.balance.
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 implies usage for refilling credits and explicitly notes it is public with no credentials needed, which is useful context. However, it does not state when to use this tool versus alternatives such as billing.balance, and no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one report by the id search returned: the full markdown text with its citations and evidence header, plus title, url and metadata. Public reports need no key; a caller's own reports need theirs.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A result id from search (a run id). |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | The report as markdown. |
| title | Yes | |
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: the authentication requirement ('Public reports need no key; a caller's own reports need theirs') and the specific output payload. This goes beyond what the annotations alone provide, justifying a 4.
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 with zero redundancy. The primary action and scope are front-loaded, and the auth note is placed at the end. Every word contributes to the agent's understanding.
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?
The tool has an output schema, so return format is covered elsewhere. The description covers the purpose, the input origin, the returned content, and auth requirements. Minor omissions like error handling are acceptable given the simplicity and the presence of structured 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?
The input schema already describes the single parameter 'id' as 'A result id from search (a run id)' with 100% coverage. The description repeats the source of the id ('the id search returned') without adding new syntax or format details. Baseline 3 is appropriate since the schema does the heavy lifting.
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 states a specific verb ('Read') and a clear resource ('one report by the id search returned') and enumerates the exact contents returned (full markdown text, citations, evidence header, title, url, metadata). This clearly distinguishes it from sibling tools like runs.get (likely for raw runs) and search (for finding ids), so an agent can immediately understand its role.
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 phrase 'by the id search returned' establishes the intended workflow (use after search) but does not explicitly name alternatives or state when not to use it. There is clear contextual guidance without exclusions, which matches a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE, no key, no account: live prices for BTC, ETH, SOL, AMZN and NVDA with the session's change, plus today's news — the platform's newest published news digest parsed into stories with source links, and the market wire's latest headlines. Refreshed every minute (prices) and every ten minutes (news). Call this first to see what the swarm's data looks like before spending anything.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| free | No | Always true — this call is never charged. |
| news | Yes | |
| next | No | How to get the same data over MCP and how to commission a real report. |
| as_of | Yes | RFC 3339 time this document was rendered. |
| prices | Yes | One entry per symbol that priced this cycle, in list order. |
| symbols | No | The fixed symbol list served. |
| attribution | No | |
| prices_as_of | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark it as read-only and non-destructive, and the description adds valuable behavioral context: no authentication needed, data refresh cadence (prices every minute, news every ten minutes), and the free/no-cost nature. It also clarifies what content will be included, which goes beyond the structured 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?
The description is dense but front-loaded, leading with the most important facts (free, no key, no account) before listing the exact data returned. Every clause adds information about scope, freshness, or usage context, with no wasted words or repetition.
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 parameterless, read-only data-viewing tool with an output schema, the description is complete. It specifies the tickers, news sources, refresh rates, and a clear invocation scenario, leaving no ambiguity about what an agent gets or when to call it.
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 tool has zero parameters and 100% schema coverage, so the input schema already fully describes the invocation surface. The description appropriately explains the data payload scope instead, which is exactly what is needed for a parameterless tool. This meets the baseline for no-parameter tools without requiring additional compensation.
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 what the tool does: it returns live prices for specific tickers and today's news from a parsed digest and market wire. It distinguishes itself from sibling tools by emphasizing that it is free, requires no key/account, and is meant as a first look at the swarm's data. Even without an explicit verb, the resource and scope are unambiguous.
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 says 'Call this first' and frames it as a pre-spending reconnaissance step, giving an unambiguous when-to-use instruction. It does not mention when not to use it or name alternatives, but the guidance is clear enough for an agent to decide to invoke it early.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The launchable modes with a one-line contract for each. Static; never charged, no credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| modes | Yes | |
| route_first | No | How to classify a freeform prompt into a mode id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, but the description adds valuable context: 'Static; never charged, no credentials needed.' This discloses that it's immutable, free, and requires no auth—details not present in 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?
Single sentence, perfectly sized. Core purpose ('launchable modes') is front-loaded, with essential caveats (static, free, no auth) stated succinctly. 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?
Given it has an output schema (so return format is defined outside the description) and zero parameters, the description covers everything an agent needs to call it correctly: purpose, static nature, cost, and auth. Nothing important is missing.
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 schema is trivially complete. Baseline for 0 params is 4; description adds no param info that's needed. No gaps to compensate.
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?
States it lists 'launchable modes' with a 'one-line contract for each,' which is a clear verb+resource. Its static nature and no-charge/no-credentials attributes further distinguish it from siblings like billing and runs 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 implies usage: to discover available modes before launching. It doesn't explicitly name alternatives or exclusion conditions, but the purpose is clear enough that an agent would know when to call it (e.g., before runs.launch).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Classify a freeform request into the right mode (research, news, finance, astrology, …) before spending a run. Never charged.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The freeform request to classify, e.g. 'compare the best espresso grinders under $300'. |
| Name | Required | Description |
|---|---|---|
| mode | Yes | The chosen mode id — pass it to runs.launch. |
| fields | No | Fields the router extracted from the prompt (mode-specific). |
| from_llm | No | True when the LLM router answered, false for the offline heuristic. |
| rationale | No | Why this mode was picked. |
| alternates | No | Other plausible modes, best first. |
| confidence | Yes | Router confidence, 0–1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read-only operation, so the description need not repeat that. It adds value by disclosing the workflow timing ('before spending a run') and the cost behavior ('Never charged'), which are behavioral traits beyond the annotations. No contradiction with the read-only hint exists.
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 short sentences deliver the core purpose, workflow context, and cost implication without any filler. The operational guidance is front-loaded, and every word 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?
For a one-parameter, read-only classifier with a full output schema, the description covers the essential facts: what it classifies, when to call it, and that it is free. Nothing an agent needs to invoke it correctly is missing.
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% and the single parameter includes a helpful example. The description does not add parameter-level detail beyond the schema, but the baseline of 3 applies because the schema already fully documents the prompt parameter.
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 a specific verb ('Classify') and resource ('freeform request') and names the classification output categories (research, news, finance, astrology). It also frames the tool's role in the workflow, distinguishing it from launching a run.
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 clearly states when to use the tool: before spending a run, to determine the right mode. It also adds a key practical qualifier, 'Never charged', which helps an agent decide to call it without cost concern. It does not name sibling alternatives explicitly, but the 'before spending a run' context is sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running job.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id returned by runs.launch. |
| Name | Required | Description |
|---|---|---|
| run_id | Yes | |
| status | Yes | 'cancelling' — the run unwinds itself; poll runs.get for the terminal state. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description does not need to restate destructiveness. It does add the useful behavioral constraint that only running jobs can be stopped, implying that already-completed or queued jobs are not the target. Still, it does not describe side effects like whether job state becomes canceled or whether resources are freed, so value beyond annotations is moderate.
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 exceptionally concise: four words with no filler. It front-loads the core action and leaves parameter details to the schema, which is the ideal structure for a simple tool.
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 single-parameter, single-action tool with a clear output schema and destructive annotation, the description is mostly complete. An agent can correctly invoke it with run_id and understand it is destructive. It could add a note about cancellation being irreversible, but annotations already cover the destructive hint.
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 schema already provides 100% coverage: run_id is required and described as 'The run_id returned by runs.launch.' The description adds no parameter-level detail beyond this, so baseline 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 'Stop a running job' uses a specific verb and resource, and clearly distinguishes runs.cancel from sibling tools like runs.launch, runs.get, and runs.report. An agent can immediately understand this is the cancellation operation.
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 implies when to use the tool: when a running job needs to be stopped. However, it does not explicitly state when not to use it or mention alternatives such as runs.get for checking status or runs.report for outcomes. Usage context is present but only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A run's status and metadata. Poll until status is completed/failed/cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id returned by runs.launch. |
| Name | Required | Description |
|---|---|---|
| meta | No | Run metadata: id, mode, title, timing. |
| error | No | Failure detail when status is failed, else null. |
| usage | No | Token meters for the run — null while the run is still running, an object once it settles. |
| status | No | running | completed | failed | cancelled. |
| cancelling | No | A stop was requested but the run has not unwound yet. |
| has_report | No | True once runs.report will answer with the report. |
| finished_at | No | RFC 3339 completion time; null while running. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context by naming the terminal statuses (completed/failed/cancelled) and indicating that the tool is meant for polling.
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 short sentences communicate the purpose, resource, and polling behavior with no filler. The key information is front-loaded and every word 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?
With one required parameter, a full output schema, and safety annotations, the description covers the main lifecycle context an agent needs. It does not mention not-found or error behavior, but that is a minor gap given the low complexity and available structured metadata.
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 input schema fully documents run_id as the value returned by runs.launch, giving 100% schema description coverage. The tool description adds no additional parameter nuance, so the baseline 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 identifies the resource (a run) and the data returned (status and metadata), and the polling instruction signals a read operation. It is specific enough to distinguish this from siblings like runs.cancel and runs.launch, though it lacks an explicit verb such as 'get' or 'retrieve'.
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 clearly states the intended usage pattern: poll until the run reaches a terminal status. It does not explicitly contrast with runs.report or runs.cancel, but the polling context is unambiguous and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch a run: agents search the web, read sources, and write a cited report — real work, done for the caller. BILLED from the caller's credits. Returns the run record; poll runs.get until completed, then runs.report. Modes: research, news, product, trips, trainer, finance, astrology, horoscope (astrology/horoscope take Birth date constraint lines — see https://ioswarm.io/llms.txt).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | A mode id from modes.list, e.g. 'research'. | |
| input | Yes | The question or brief. astrology/horoscope take constraint lines ('- Birth date: YYYY-MM-DD', optional Birth time + Timezone, Latitude/Longitude) — contract at https://ioswarm.io/llms.txt. | |
| max_workers | No | Optional parallelism override (worker count). Omit for the mode default. |
| Name | Required | Description |
|---|---|---|
| run_id | Yes | The run's id — pass to runs.get / runs.report / runs.cancel. |
| status | Yes | 'running' on acceptance. |
| estimated_credits | No | The credit estimate reserved at launch; settled from real usage at completion. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behaviors not expressed in the annotations: the run is billed from the caller's credits, it is asynchronous ('poll runs.get until completed'), and it performs real external work. The openWorldHint only weakly implies external action, so the descriptive detail adds substantial transparency. No contradiction with readOnlyHint=false or destructiveHint=false.
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 one dense paragraph that front-loads the action and billing, then gives lifecycle instructions and mode guidance. Every clause contributes operational value, and there is no redundant restatement of the schema.
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?
The output schema covers the return record shape, so the description focuses on what structured fields cannot convey: the async polling workflow, the follow-up report step, billing consequences, and special input formats. An agent has enough context to invoke this tool correctly and continue the workflow.
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?
Although schema coverage is 100%, the description adds a concrete list of supported mode values (research, news, product, trips, trainer, finance, astrology, horoscope) that the schema lacks because there is no enum. It also enriches the input parameter by explaining constraint-line syntax for astrology/horoscope and linking to the full contract, materially improving invocation correctness.
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 a specific verb and resource ('Launch a run') and explains exactly what a run does: agents search the web, read sources, and produce a cited report. It clearly distinguishes this from sibling tools by framing it as the start of a workflow that continues with runs.get and runs.report.
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 gives clear post-launch guidance: poll runs.get until completed, then runs.report. It also lists modes and points to an external contract for special input constraints. It does not explicitly state when not to use this tool or compare alternatives like route.classify, but the lifecycle and context are strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The finished, cited report for a completed run (report_text is markdown).
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id returned by runs.launch. |
| Name | Required | Description |
|---|---|---|
| report_text | No | The full report as markdown, citations inline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond the annotations by specifying that the report is finished, contains citations, and that report_text is markdown, which informs the agent about the output format and content expectations.
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 a single compact sentence with no filler. It front-loads the key idea, names the output field, and specifies the format, making every word useful.
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 a single parameter, a full schema description, safe read-only annotations, and an existing output schema, the description covers what is needed: the precondition of a completed run and the markdown format of the report. No critical guidance is missing for an agent to invoke it 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 for the single parameter is 100%, as run_id is described as 'The run_id returned by runs.launch.' The description itself adds no additional parameter context, so the schema carries the full burden. Baseline 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 identifies the resource as 'the finished, cited report for a completed run' and clarifies that report_text is markdown. This makes the function's object clear, but it is phrased as a noun phrase rather than an explicit action verb like 'retrieves' or 'returns', and it does not explicitly distinguish itself from the sibling runs.get tool.
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 phrase 'for a completed run' implies the tool should be used after a run has finished, which is a useful precondition. However, there is no explicit statement about when not to use it, nor does it compare itself to alternatives such as runs.get, so the usage guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a run finishes, then return its record — and its report when it completed. Runs take 3–10 minutes; call this instead of polling runs.get in a loop. Returns early with timed_out=true after timeout_secs (default 90, max 240): call it again with the same run_id to keep waiting. Never charged.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id returned by runs.launch. | |
| timeout_secs | No | How long this call may wait before returning the current status. Default 90, max 240. |
| Name | Required | Description |
|---|---|---|
| run | No | The run record (as runs.get). |
| report | No | The report (as runs.report) when status is completed, else null. |
| run_id | Yes | |
| status | Yes | running | completed | failed | cancelled. |
| timed_out | Yes | True when the wait window elapsed first — call again. |
| waited_secs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it blocks, returns early with timed_out=true after timeout_secs, can be called again with the same run_id, and is never charged. It doesn't describe the exact return structure, but an output schema exists, so that's not required.
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 compact and front-loaded: it states the core behavior first, then timing, then timeout handling, then cost. Every sentence earns its place, and there is no fluff or repetition of schema details.
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 (blocking wait with timeout), the description covers all essential aspects: what it does, when to use it, how to handle timeouts, cost implications, and the fact that it returns a report. The output schema exists, so return values are already documented. Sibling tools like runs.cancel and runs.launch are distinct enough that no further differentiation is needed.
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 documents both parameters. The description adds context for timeout_secs (default 90, max 240) and run_id (returned by runs.launch), but these are also in the schema. The description's main added value is the behavioral guidance around timeout_secs, not new parameter semantics. Baseline 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's purpose: 'Block until a run finishes, then return its record — and its report when it completed.' It uses a specific verb ('block', 'return') and resource ('run'), and distinguishes itself from polling runs.get by explicitly saying 'call this instead of polling runs.get in a loop.'
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 tells the agent when to use this tool: instead of polling runs.get in a loop, and how to handle timeouts: 'call it again with the same run_id to keep waiting.' It also provides timing context ('Runs take 3–10 minutes') and notes the tool is 'Never charged,' which helps the agent decide to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the swarm's published research: the featured shelf, the operator's daily news / markets / AI digests, and — when a key is presented — the caller's own reports. Every hit is a finished, cited, evidence-graded report. Returns {results:[{id,title,url}]}; pass an id to fetch. No key needed for the public corpus. (The research-connector contract: this is what a ChatGPT or Claude connector calls.)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Words to match against report titles and text. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: every hit is a finished, cited, evidence-graded report; the return shape is disclosed; and the key-based access to caller's own reports is mentioned. It doesn't describe pagination or rate limits, but for a read-only search tool with annotations, this is strong additional context.
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 compact, front-loaded with the core purpose, and every sentence earns its place: scope, result quality, return shape, key requirement, and contract context. It is information-dense without being bloated.
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 single-parameter read-only search tool with a full output schema, the description is complete. It covers what is searched, what is returned, how to use the result (pass id to fetch), and access requirements. Nothing an agent needs to call it correctly is missing.
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 documents the single 'query' parameter. The description adds that the query matches against 'report titles and text', which is a slight enrichment beyond the schema's 'Words to match against report titles and text' – actually the description and schema say nearly the same thing. Baseline 3 is appropriate because the schema carries the parameter semantics fully.
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 states a specific verb ('Search') and a precise resource ('the swarm's published research'), and enumerates the sub-corpora (featured shelf, operator digests, caller's own reports). It also distinguishes itself from the sibling 'fetch' by noting that hits return ids and that an id can be passed to fetch. This is a clear, specific statement of what the tool does.
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 says when to use this tool: to search the public corpus, with no key needed. It also mentions the alternative path ('pass an id to fetch') and the research-connector contract, which tells an agent this is the standard search entry point. This is explicit usage guidance with a clear exclusion (no key needed for public corpus) and a pointer to the sibling fetch tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
fetchsearchruns.waitmarket.pulseruns.get4 fields changedOutput schema / properties / error / typeAdded value: +[
+ "string",
+ "object",
+ "null"
+]Output schema / properties / finished_atAdded value: +{
+ "description": "RFC 3339 completion time; null while running.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Output schema / properties / usage / descriptionPrevious value: -"Token meters for the run."New value: +"Token meters for the run — null while the run is still running, an object once it settles."Output schema / properties / usage / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]billing.balancebilling.topup_termsmodes.listroute.classifyruns.cancelruns.getruns.launchruns.reportVedic and Western astrology for AI agents: charts, dasha, matchmaking, panchanga, numerology, tarot.
Real astrology for AI agents: cosmic weather, synastry, timing, astrocartography, and divination.
Western natal charts, horoscopes, transits and synastry for AI agents, verified vs NASA JPL.
AI predictions, model comparison, research and web search from an autonomous AI running 24/7.
Add one secure layer between your agents and this server.
