Skip to main content
Glama

Why the leads are dear or ran out

diagnose_search

The criteria revision («Изменить критерии»): while a search asks about a higher price, or when a finished search ran out of people, works out which criteria hold it back and proposes changes, each combination with its price in credits and the leads it may give. Takes up to ~75 s. Then revise_search with the chosen proposal ids. [REST: POST /api/tasks/{id}/revise/diagnose]

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task_id": "<task_id>"
    },
    "name": "diagnose_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
task_idYesThe search id (task id), e.g. from list_searches or create_search.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, non-destructive), the description discloses the key behavioral facts an agent needs to plan: ~75 s runtime, that output is combinations each carrying a credit price and an expected lead yield, and that the actual change happens later via revise_search. It does not explain why the tool is non-read-only (does it consume credits or create a background task?), nor whether repeated diagnosis runs accumulate cost.

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?

It is a single dense passage with no filler: trigger conditions, output content, latency, next step, and REST route each appear once. Minor noise comes from the untranslated UI label «Изменить критерии» and the awkward clause structure, which slow parsing more than the length does.

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

Completeness3/5

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

There is no output schema, so the description must carry the return contract, and it only partially does — it says combinations come with a credit price and expected leads, but never says where the proposal ids live in the response, how many are returned, or what an empty result means. Latency and the handoff to revise_search are covered, so the gap is specifically in the response shape an agent must parse.

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

Parameters3/5

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

With a single parameter and 100% schema description coverage, the schema already documents task_id, its pattern, and where to obtain it (list_searches / create_search). The description adds no further meaning about the id's scope. Baseline 3 applies because the schema carries the parameter burden.

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?

The description names a specific operation: diagnosing which criteria hold a search back when the price is too high or the pool is exhausted, and producing priced change proposals. It also distinguishes itself from the sibling it hands off to ("Then revise_search with the chosen proposal ids"). The wording is a non-native translation ("while a search asks about a higher price," "the leads are dear"), which slightly muddies an otherwise clear purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states both trigger conditions explicitly: asking price is higher than expected, or a finished search ran out of people. It also gives the follow-up path (call revise_search with the chosen proposal ids), which tells the agent this tool is a decision step, not an execution step. It stops short of stating when NOT to use it (e.g. before the search has run at all) or what to do if no proposals come back.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources