Skip to main content
Glama
mmadfox

swag2mcp

by mmadfox
OverviewSchemaRelated ServersScoreDiscussions
Go
Hybrid

response_outline

Read-onlyIdempotent

Inspect the structure of a large saved JSON response to see keys, types, and array lengths before exploring further.

Instructions

response_outline

Returns a high-level structural summary of a large JSON response file that was saved to disk by invoke. It does not return the actual data — only the shape, keys, array lengths, and hints that help decide how to explore the file next.

When to use

Use this tool immediately after invoke returns a fileRef because the response body was too large. It is the first and mandatory step in exploring a saved response file.

When NOT to use

  • Do NOT use bash, cat, head, tail, file, open, less, more, or any external command to read fileRef.path.

  • Do NOT ask the user to open the file manually.

  • Do NOT try to guess the file contents. Only the response_* tools may read saved response files.

Parameters

  • path (required): The absolute file path from fileRef.path returned by invoke.

  • maxDepth (optional): Maximum recursion depth when inspecting nested objects and arrays. Default is 3.

  • maxArrayItems (optional): How many array items to inspect for detailed key/type information. Default is 5.

Returns

A structural outline containing:

  • type: root JSON type (object, array, etc.).

  • size: file size in bytes.

  • lineCount: number of lines in the file.

  • depth: maximum nesting depth inspected.

  • structure: recursive map of keys, types, array lengths, and sample items.

  • schemaHint: one-line summary of the top-level shape.

  • compressionHints: suggested response_compress calls to shrink the file.

  • navigationHints: top-level paths and arrays with lengths, useful for response_slice.

Example workflow

invoke returns fileRef.path = /.../responses/example-get-pets-abc123.json
  ↓
response_outline({"path": "/.../responses/example-get-pets-abc123.json"})
  ↓
response_compress({"path": "...", "jsonPath": "pets", "mode": "first_of_array"})
  ↓
response_slice({"path": "...", "jsonPath": "pets.0"})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesrequired,Absolute path returned in fileRef.path
maxDepthNooptional,Max recursion depth (default 3)
maxArrayItemsNooptional,How many array items to inspect (default 5)

Tool Definition Quality

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals key behavioral traits: it does not return the actual data, it serves as a gatekeeper for subsequent exploration, and it enforces a policy that only response_* tools may read saved files. These insights are not present in the annotations and add significant context for the agent.

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 longer than minimal, but it is well-structured with clear headers (When to use, When NOT to use, Parameters, Returns, Example workflow). Each section serves a distinct purpose, especially the explicit forbidden commands list. While verbose, it front-loads the core purpose and remains organized, earning a 4 rather than a 5.

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?

With no output schema, the description compensates by providing a detailed 'Returns' section listing the outline fields (type, size, lineCount, depth, structure, schemaHint, compressionHints, navigationHints). It also includes an example workflow showing how it chains with response_compress and response_slice, making the tool's role fully understandable.

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?

Schema coverage is 100% with each parameter described inline. The description's Parameters section restates the same information (path from fileRef.path, maxDepth default 3, maxArrayItems default 5) without adding new semantics. Since the schema already carries the meaning, the baseline of 3 is appropriate; the description adds no extra clarity beyond the structured data.

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 clear, specific statement: 'Returns a high-level structural summary of a large JSON response file... It does not return the actual data — only the shape, keys, array lengths, and hints...' This identifies the exact verb ('Returns'), resource ('JSON response file'), and distinguishes the tool from siblings like response_compress and response_slice, which manipulate data.

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?

The 'When to use' section explicitly instructs to use this tool 'immediately after invoke returns a fileRef' and labels it the 'first and mandatory step.' The 'When NOT to use' section names specific forbidden alternatives (bash, cat, head, tail, etc.) and states that only response_* tools may read saved files. This provides clear direction on when to use versus alternatives.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mmadfox/swag2mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server