Skip to main content
Glama

read_doc_section

Read-onlyIdempotent

Reads one ROS 2 documentation section per call, up to 2,000 characters, and returns next_offset to continue long sections.

Instructions

Read one documentation section, up to 2000 characters per call; pass next_offset to continue a long section.

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": {
      "section_id": "<section_id>"
    },
    "name": "read_doc_section"
  }
}

Input Schema

NameRequiredDescriptionDefault
offsetNo
section_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral information beyond them: the 2000-character truncation cap and the pagination contract, which an agent cannot infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

A single front-loaded sentence with no filler; the truncation limit and continuation mechanism are both surfaced immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read, the pagination contract is the key thing to convey and it does so. However, the "next_offset" label does not exist in the schema, and the description never says where that value is returned from, leaving an agent to guess at the continuation loop.

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 description coverage is 0%, so the description must carry parameter meaning. It explains the offset parameter's purpose but calls it "next_offset" while the schema names it "offset," creating a naming mismatch, and it never explains what section_id is or where it comes from.

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?

States a specific verb and resource ("Read one documentation section") plus a concrete scope limit (2000 characters per call). It implicitly separates itself from bulk retrieval by emphasizing "one" section, but it never names the sibling search_docs it would naturally pair with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives usable guidance for the continuation case ("pass next_offset to continue a long section"), which tells the agent how to handle truncation. It offers no guidance on when to use this versus search_docs or how to obtain a section_id in the first place.

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