Skip to main content
Glama

commands

Read-onlyIdempotent

The commands a citizen may call, with parameters and descriptions; the same verbs as the vocabulary's signatures (allowed is which actor kinds may call each: you are a citizen). Long; verb returns one. No name needed; quickstart shows one worked line per verb.

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

Input Schema

NameRequiredDescriptionDefault
verbNoOne command alone, by its verb (story, dig, …).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / verb
      Added value: +{
      +  "description": "One command alone, by its verb (story, dig, …).",
      +  "type": "string"
      +}
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context on top: the response is long by default, `verb` narrows it to one entry, and each entry carries an `allowed` field indicating which actor kinds may call it. That last point tells the agent how to interpret the payload, which is beyond what annotations provide. It does not describe ordering, pagination, or size bounds, so it is not 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short and front-loads the core purpose, but the style is telegraphic, with nested parentheticals and backticked cross-references that take a pass to parse. 'No name needed' is an unearned fragment whose referent is unclear. It is compact but not clean.

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 read-only, one-optional-parameter listing tool with no output schema, the description covers purpose, the two call modes, a warning about output length, and the meaning of the `allowed` field within each entry. That is close to sufficient. A short note on what a command entry actually contains beyond `allowed` would close the remaining gap.

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% and the `verb` parameter is already documented with examples (story, dig), so baseline is 3. The description adds meaning the schema does not: omitting `verb` yields the full long listing while supplying it returns exactly one command, which is the key semantic distinction for this optional parameter. The phrase 'No name needed' is unexplained and muddies rather than clarifies.

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 states the resource (the set of commands a citizen may call) and what each entry contains (parameters and descriptions), and ties it to the vocabulary's signatures so the agent knows the shape of the data. It does not lead with a clean verb like 'list', and the meaning of the noun phrase depends on understanding the surrounding vocabulary concept, so it falls short of a crisp 5.

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 explicitly distinguishes the two modes: called without `verb` it is the long full listing, and `verb` returns a single command. It also names `quickstart` as the alternative for a worked example line per verb, which is genuine routing guidance. What is missing is an explicit 'use this when you need full parameter detail rather than an example' framing, so it stops at 4.

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.