Skip to main content
Glama

Onsa

by ai.onsa
OverviewAdmin

Fetch search results

fetch_leads
Read-onlyIdempotent

Get the status/results of a find_leads job by jobId. "pending" means the search is still running (leads may already hold a partial list); "completed" means the agent delivered a batch of leads — it is NOT a guarantee that no more will arrive, so if total is still rising keep polling. "stalled" means no leads arrived for ~15 minutes — the agent asked a question, errored, or never delivered; STOP polling, read agentMessage for the reason, relay it to the user and re-run find_leads with the answer folded into the query. Also returns total (leads in this response), campaignId (pass it to get_campaign / get_campaign_leads / get_campaign_stats) and campaignUrl — a deep link straight into the prospects tab for this search in Onsa. agentMessage is agent text from this campaign's chat, filtered to what was said AFTER this job started — so it is never a reply that predates your request, but on a campaign with several searches it CAN be a late message from an earlier one. A null value does NOT mean the agent is silent: artifact-only messages carry no text, and an agent that ERRORED writes nothing here at all. Treat null as "no news", apply the 15-minute rule, and never read it as proof it is still working. If it is asking for something and no leads are arriving, STOP POLLING, relay that question to the user, and start a new find_leads with the answer folded into the query; the agent cannot be replied to through this API. Each lead carries name, companyName, linkedInUrl, position, headline, location, industry, companyUrl, email (often null), and — most usefully — score (1–5) and scoreExplanation, the reasoning for why this person matches the ICP.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
jobIdYesThe jobId returned by find_leads — never invent one
limitNoHow many leads to return (default 100)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
jobIdYes
leadsYes
totalYes
statusYesOne of: "pending" (search still running), "completed" (a batch of leads arrived — not a promise that no more will), "stalled" (no leads after ~15 minutes; read agentMessage for the reason and stop polling). Treat an unrecognised value as pending.
newLeadsYes
returnedYes
campaignIdYes
campaignUrlYes
agentMessageYes

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / status / description
      Added value: +"One of: \"pending\" (search still running), \"completed\" (a batch of leads arrived — not a promise that no more will), \"stalled\" (no leads after ~15 minutes; read agentMessage for the reason and stop polling). Treat an unrecognised value as pending."
    • removedOutput schema / properties / status / enum
      Removed value: -[
-  "pending",
-  "completed"
-]
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Goes far beyond the readOnlyHint annotation by explaining that artifact-only messages carry no text, that null agentMessage does not mean the agent is silent, and that errors produce no message. The 15-minute rule and the inability to reply through this API are critical behavioral constraints explicitly disclosed. No contradiction with annotations.

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?

The description is front-loaded with the primary purpose and then covers all edge cases, but it is lengthy and slightly repetitive (e.g., 'folded into the query' and the 15-minute rule appear multiple times). While every point is substantive, trimming redundancy would improve conciseness without losing information.

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

Completeness5/5

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

Given the complexity of the tool (status polling, null handling, error scenarios, lead field semantics), the description leaves no gap. It explains the meaning of each status, the behavior for null agentMessage, the warning about artifact-only messages, and the fallback to find_leads. The context is fully covered.

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

Parameters5/5

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

Both parameters are fully described: jobId must come from find_leads and never be invented, and limit has a default of 100 with min/max enforced. The description also clarifies what each lead field represents (name, companyName, email, score, scoreExplanation), enriching the user's understanding of output even if not strictly parameter-related.

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

Purpose5/5

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

The description clearly states the tool fetches results/status of a find_leads job by jobId, specifies the three possible statuses (pending, completed, stalled) with behavior for each, and distinguishes it from related tools like find_leads and get_campaign. The core purpose is unambiguous and specific.

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?

Provides explicit guidance on when to poll, when to stop (stalled with agent question), how to handle null agentMessage (treat as no news, apply 15-minute rule), and when to re-run find_leads with the answer folded into the query. Also warns not to invent a jobId. This is actionable and precise.

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

All Onsa toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources