Skip to main content
Glama
Sign In

AIsa Web Search & Research

by one.aisa
OverviewDiscussionsAdmin

Explain Search Results

post_scholar_search_explain
Destructive

Explain a result set you already fetched. Unlike the three search endpoints this one takes a JSON body: search_id (required — the id returned by post_scholar_search_web, post_scholar_search_scholar or post_scholar_search_mixed), plus detail_level (BRIEF / MODERATE / DETAILED), language, and response_mode. ⚠️ Use response_mode: NON_STREAMING. It returns {"message": "…"} as JSON, measured at about 2 KB. The COMPLETE and INCREMENTAL modes emit server-sent events in which each event repeats the whole answer so far — the identical explanation measured 177 KB that way, roughly 90 times larger, and a tool call cannot consume a stream incrementally anyway. It only ever explains an existing search; it cannot run one.

Published reference price: $0.01 USD per successful request. Account-specific pricing and final settlement may differ.

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": {
      "body": "<body>"
    },
    "name": "post_scholar_search_explain"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / body
      Added value: +{
+  "properties": {
+    "detail_level": {
+      "default": "MODERATE",
+      "description": "Level of detail in the explanation",
+      "enum": [
+        "BRIEF",
+        "MODERATE",
+        "DETAILED"
+      ],
+      "type": "string"
+    },
+    "language": {
+      "default": "en",
+      "description": "Language code for the explanation (e.g., en, zh, ar)",
+      "example": "ar",
+      "type": "string"
+    },
+    "response_mode": {
+      "default": "NON_STREAMING",
+      "description": "Format of the explanation response. COMPLETE and INCREMENTAL stream server-sent events; NON_STREAMING returns a JSON response.",
+      "enum": [
+        "COMPLETE",
+        "INCREMENTAL",
+        "NON_STREAMING"
+      ],
+      "type": "string"
+    },
+    "search_id": {
+      "description": "ID of the search to explain",
+      "type": "string"
+    }
+  },
+  "required": [
+    "search_id"
+  ],
+  "type": "object"
+}
    • removedInput schema / properties / detail_level
      Removed value: -{
-  "default": "MODERATE",
-  "description": "Level of detail in the explanation",
-  "enum": [
-    "BRIEF",
-    "MODERATE",
-    "DETAILED"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / language
      Removed value: -{
-  "default": "en",
-  "description": "Language code for the explanation (e.g., en, zh, ar)",
-  "example": "ar",
-  "type": "string"
-}
    • removedInput schema / properties / response_mode
      Removed value: -{
-  "default": "NON_STREAMING",
-  "description": "Format of the explanation response. COMPLETE and INCREMENTAL stream server-sent events; NON_STREAMING returns a JSON response.",
-  "enum": [
-    "COMPLETE",
-    "INCREMENTAL",
-    "NON_STREAMING"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / search_id
      Removed value: -{
-  "description": "ID of the search to explain",
-  "type": "string"
-}
    • changedInput schema / required
      Previous value: -[
-  "search_id"
-]New value: +[
+  "body"
+]
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Without relying on annotations it discloses the return shape and size (~2 KB JSON vs ~177 KB for the SSE modes), explains that each streamed event repeats the whole answer so a tool call cannot consume it incrementally, and states the cost ($0.01). That is far more than the annotations provide. It does not, however, reconcile the declared destructiveHint=true / readOnlyHint=false for an operation the description frames as a pure explanation, so the mutation profile of this call is left unexplained.

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?

Key constraint is front-loaded, and the SSE-size comparison earns its length by justifying the response_mode recommendation. Some sentences restate schema content (the enum meanings of COMPLETE/INCREMENTAL/NON_STREAMING), and the pricing block plus emoji/bold add visual noise, but overall it is proportionate to the tool's complexity.

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?

For a nested-body tool with streaming modes and a cost, the description covers purpose, inputs, response format, cost, and the hard limitation. An output schema exists, so it need not detail return values, and it briefly does anyway. The only uncovered area is the destructive/read-only behavior the annotations assert, which the description never addresses.

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

Parameters4/5

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

Reported schema coverage is 0% (the top-level 'body' wrapper carries no description), so the description has to compensate, and it does: it enumerates search_id (with its origin), detail_level, language, and response_mode, and adds non-obvious meaning by prescribing NON_STREAMING and tieing search_id to a prior search call. The one gap is that, like the schema, it enumerates nothing about defaults for language/detail_level.

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 opens with a specific verb+resource ('Explain a result set you already fetched') and immediately differentiates itself from the sibling search endpoints by noting they produce the search_id it consumes. An agent can tell what this does and how it differs from post_scholar_search_web/scholar/mixed without opening any schema.

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 states the precondition explicitly ('a result set you already fetched'), names the three sibling tools that generate the required search_id, and states the exclusion 'it cannot run one.' It also gives concrete selection guidance for response_mode ('Use response_mode: NON_STREAMING'). This is explicit when/when-not/alternative coverage.

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

All AIsa Web Search & Research 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