Skip to main content
Glama
cmgmyr

hive

by cmgmyr
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

pad_read

Idempotent

Read a shared pad's content, revision, and metadata by ID or name, with optional UTF-16 offset and limit for paging large text.

Instructions

Read a pad's content, revision, and metadata by pad_id or name. Optional offset and limit use UTF-16 code units and are nonnegative safe integers. There is no default cap; a cut inside a surrogate pair moves back one code unit, or forward if moving back would return nothing, and the result reports the effective offset.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNo
limitNoRequested UTF-16 code units to read; no default cap. An end cut inside a surrogate pair moves back one code unit, or forward if moving back would return nothing.
offsetNoStart index in UTF-16 code units; an index inside a surrogate pair moves back one code unit.
pad_idNo
project_idNoDifferent project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.7.0
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "Requested UTF-16 code units to read; no default cap. An end cut inside a surrogate pair moves back one code unit, or forward if moving back would return nothing.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Start index in UTF-16 code units; an index inside a surrogate pair moves back one code unit.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
  2. First observedv1.0.0

TDQS

A3.7/5.0
Behavior4/5

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

The description adds real behavioral context beyond the annotations: offset/limit are measured in UTF-16 code units, there is no default cap, an end cut inside a surrogate pair moves back one code unit (or forward if moving back yields nothing), and the result reports the effective offset. The unexplained tension is that annotations set readOnlyHint=false while the tool is described purely as a read; if readOnlyHint was set deliberately this would be an inconsistency, though false is also the MCP default for an unset hint.

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?

Three sentences, no filler, and the purpose is front-loaded before the pagination mechanics. The surrogate-pair sentence is dense but every clause carries load-bearing semantics rather than restating the name.

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 paginated read with no output schema, the description adequately covers what is returned (content, revision, metadata) and how offset/limit behave at the edges. It omits error behavior, size limits, and whether revision must be supplied for consistency, but nothing essential for a correct first call is missing.

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 60%: limit and offset already carry nearly the same UTF-16/surrogate wording the description repeats, and project_id has its own detailed scope note. The description's only net-new parameter information is that either pad_id or name may be used as the identifier and that the effective offset is echoed back, so it does little more than the schema already does.

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 opens with a specific verb and resource: 'Read a pad's content, revision, and metadata by pad_id or name.' That clearly distinguishes it from pad_write/pad_append/pad_edit/pad_delete and pad_list. It stops short of explicitly naming or contrasting those siblings, so it lands just below the top tier.

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?

Usage is implied by the verb 'Read' and the accepted identifiers, but there is no explicit when-to-use guidance: it does not say when to prefer pad_id over name, when to reach for pad_read rather than pad_list, or what to do if the pad does not exist. The only scope guidance lives in the schema (project_id), not the description.

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

Deploy Server

Other Tools