Skip to main content
Glama
Sign In
Paperboy

Paperboy

Official
by sudostash
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

extract_text

Read-onlyIdempotent

Pulls text from PDF files, optionally for specific pages like "1-3,7", returning content and a truncation flag. Handles password-protected PDFs with local password entry.

Instructions

Extract text from all pages or a page spec (e.g. "1-3,7"). Returns text + truncation flag.

Any password argument can be "ask": the user then types it on a local page, so it never passes through the chat.

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": {
      "input_path": "<input_path>"
    },
    "name": "extract_text"
  }
}

Input Schema

NameRequiredDescriptionDefault
pagesNo
passwordNo
max_charsNo
input_pathYes

Output Schema

NameRequiredDescriptionDefault
pathYes
textYes
truncatedYes
pages_readYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "pages_read": {
+      "title": "Pages Read",
+      "type": "integer"
+    },
+    "path": {
+      "title": "Path",
+      "type": "string"
+    },
+    "text": {
+      "title": "Text",
+      "type": "string"
+    },
+    "truncated": {
+      "title": "Truncated",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "path",
+    "pages_read",
+    "truncated",
+    "text"
+  ],
+  "title": "TextResult",
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: the "ask" password convention that keeps credentials out of the chat transcript, plus a truncation flag. It still omits what triggers truncation or how encrypted/failed PDFs behave.

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?

Two tight sentences, front-loaded with purpose and scope, then a distinct security note about passwords. Each sentence earns its place; only minor redundancy exists between "Returns text + truncation flag" and the output schema.

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 4-parameter read tool with an output schema and rich annotations, this covers purpose, page selection, password handling and truncation awareness. The remaining gap is max_chars behavior — how it interacts with the truncation flag — which an agent calling the tool would benefit from knowing.

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 0%, so the description must carry the load. It clarifies two of four parameters well — the pages spec format with a concrete example and the special "ask" value for password — but says nothing about max_chars (only obliquely via the truncation flag) or input_path semantics.

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 ("Extract text") and scopes it to "all pages or a page spec (e.g. \"1-3,7\")", which tells an agent exactly what it operates on. It does not explicitly differentiate itself from the sibling search_text or export_markdown, so it falls short of a 5.

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 name and the page-scoping sentence: read the full document or a subset. There is no explicit when-to-use versus search_text (find text without extracting) or export_markdown (formatted output), and no stated preconditions beyond the password note.

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