Skip to main content
Glama

handoff_read

Provides a one-call overview of files or folders with real line numbers, returning matching lines, code outlines, log profiles, and JSON/CSV shapes to guide targeted reads.

Instructions

A one-call overview of files or folders, in a fixed format with real line numbers. For one specific question, your own search and partial reads are usually cheaper. Code does the work, with no model: a named identifier or quoted string gets the matching lines; source code gets an outline (definitions, docstrings, constants); logs get a profile (each kind of line with counts, odd values, first big jump, rare lines in full); JSON and CSV get their shape. Plain text goes to the local model only if the user turned that on. The first line says which tool ran. Every line number is real: Read the lines that matter before acting on them.

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": {
      "paths": "<paths>"
    },
    "name": "handoff_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
rootNoOptional folder to show paths relative to.
toolNoOptional: force one tool.
pathsYesAbsolute file or folder paths.
includeNoOptional file name patterns for folders, e.g. ["*.py"].
questionNoOptional: what you want to know. Put exact names in backticks to get their lines.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full burden and does substantial work: it discloses that the work is deterministic ('Code does the work, with no model'), that plain text is the only path that may touch the local model and only if the user opted in, and that the first output line identifies which mode ran. It does not state permissions, cost/latency, or error behavior, so it stops short of 5.

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?

Front-loads the identity and format guarantee, then the usage exclusion, then the mode behaviors, so a reader can stop early. The log-profile clause and the multi-mode sentence are dense and crammed with parentheticals, which costs some scannability.

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 five-parameter, no-output-schema, no-annotation tool, the description covers the essential gaps: dispatch behavior, the opt-in privacy caveat, and the header-line convention. It does not sketch what the 'fixed format' actually looks like per mode, which leaves some ambiguity about the return payload, but not enough to block a correct call.

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%, so the baseline is 3 and the schema already documents all five parameters, including the backtick convention the description repeats. The description's marginal addition is the auto-dispatch model behind the optional 'tool' parameter, which explains why most callers should omit it.

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 concrete verb+resource ('a one-call overview of files or folders') plus the output contract ('fixed format with real line numbers') and enumerates the per-input-type behaviors (identifier match, source outline, log profile, JSON/CSV shape). What's missing is any explicit differentiation from the sibling handoff_profile, even though 'logs get a profile' overlaps that name.

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?

Gives an explicit when-not: 'For one specific question, your own search and partial reads are usually cheaper,' which routes the agent away from this tool for narrow lookups. It also gives a follow-up rule ('Read the lines that matter before acting on them'), so both the selection decision and the post-call behavior are specified.

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