Skip to main content
Glama

Page, cancel or release a search

nas_search_results
Read-only

Retrieve more pages, cancel, or discard a NAS file search task started by nas_search_files, paginating with offset, sort_by and order so results neither overlap nor skip entries.

Instructions

Work with a search started by nas_search_files, identified by its task_id. action "page" returns another page: entries are in data.ordered_items[] (there is no results wrapper here, unlike nas_search_files). Pass the offset from the previous next_offset and the same sort_by and order as the original search, otherwise pages overlap or skip entries. The search is exhausted only when a page has no next_offset; do not use total_count to decide. "cancel" stops a search that is still running and keeps what was found. "remove" discards the stored search task and its results; it never touches any file. A task that was already removed reports "not found", which is not a failure worth retrying.

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": "nas_search_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoResults per page (max 500).
orderNoSort direction.
actionNoWhat to do with the search task.page
offsetNoFor "page": the next_offset of the previous page.
sort_byNoSort key. Use the same sort_by and order on every page of one search.name
task_idYesdata.task_id from nas_search_files.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes further by scoping the one state-changing action: "remove" discards the stored search task and its results but never touches any file, which reconciles the delete verb with the read-only annotation rather than contradicting it. It also discloses that cancel preserves partial results and that already-removed tasks report "not found" without being a retryable failure. It does not state what cancel/remove return, which keeps it short of a 5.

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 task identification, then walks the three actions in order; nearly every clause carries operational information. The parenthetical asides and nested quoting around "not found" make it denser than it needs to be, but nothing is padding.

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?

For a multi-action tool with no output schema, it supplies the return structure that matters (data.ordered_items[], next_offset present or absent) and closes the risky paths: pagination drift, premature termination, and post-removal errors. Together with the annotations, an agent has everything needed to call it correctly on the first try.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: offset must be the next_offset from the previous page, and sort_by/order must match the original search on every page. It does not discuss limit or the sort_by key choices, which the schema already covers.

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?

States specific verbs (page/cancel/remove) against a specific resource (a search task identified by task_id), and explicitly distinguishes its return shape from the sibling nas_search_files ("there is no results wrapper here, unlike nas_search_files"). An agent can tell exactly which tool to reach for and what it operates on.

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?

Gives when-to-use for each action variant, plus hard prerequisites for correct paging (reuse the same sort_by and order, feed next_offset into offset) and the consequence of getting it wrong (overlap or skipped entries). It also names the correct termination condition (no next_offset) and warns against using total_count, and tells the agent that a removed task's "not found" should not be retried.

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