Skip to main content
Glama
This connector has been deprecated

Server capabilities and search pitfalls

shamela_get_brief
Read-onlyIdempotent

Return this server's machine-readable capability handshake: capabilities, numeric limits, retired tool names with their replacements, and traps (ways a result misleads, each with the response field that proves it fired). Call it first from a programmatic client: inputs are strict, so an argument an older build lacks (e.g. shape, response_format:'none') is a hard validation error that fails the whole call, and tools/list cannot reveal argument support — gate each new argument on its capability string. Cache by brief_hash and re-fetch only when it changes. Constants only: needs no library access and does not fail. Example: {} or {response_format:'json'}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "shamela_get_brief"
  }
}

Input Schema

NameRequiredDescriptionDefault
response_formatNoFormat of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief).markdown

Output Schema

NameRequiredDescriptionDefault
trapsNo
limitsNoNumeric server limits by name.
truncatedNo
brief_hashNoDigest of every other field; re-fetch only when it changes.
capabilitiesNoArguments and response fields this build supports; gate new arguments on these.
rows_droppedNo
tool_aliasesNoRetired tool names mapped to their replacement and argument changes.
server_versionNoThis build's version.
truncation_messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish read-only, idempotent, non-destructive, non-open-world behavior, but the description adds substantial traits they do not cover: it is constants-only, requires no library access, and 'does not fail', versus other tools whose strict input validation fails the whole call. It also discloses the caching contract via brief_hash, which is operationally important and absent from the 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?

Purpose is front-loaded in the first clause, followed by usage, caching, and failure semantics in a logical order, and the closing example is compact. It is dense and slightly long for a single-paragraph description, but each sentence carries distinct operational information rather than restating the schema.

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 an output schema present, the description need not explain return values, and it does not. For a bootstrap tool it covers everything an agent needs: when to call, what it yields, the validation hazard, the caching strategy, and the fact that it cannot fail — nothing material is missing.

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 description coverage is 100% and the single enum parameter is fully documented in the schema, so the baseline is 3. The description adds marginal value by giving concrete invocation examples ('{}' or '{response_format:\'json\'}') and by flagging response_format:'none' as a capability-gated argument, which tells the caller why that enum value may be rejected on an older build.

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 names a specific verb+resource ('Return this server's machine-readable capability handshake') and enumerates the payload precisely: capabilities, numeric limits, retired tool names with replacements, and traps. This is clearly distinguishable from siblings like shamela_search or shamela_get_details, which operate on library content rather than server metadata.

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 gives an explicit directive — 'Call it first from a programmatic client' — and explains the condition that makes it necessary: strict inputs mean an unsupported argument (shape, response_format:'none') is a hard validation error, and tools/list cannot reveal argument support. It also says how to use the result (gate each new argument on its capability string) and when to re-call (only when brief_hash changes).

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