DocImprint
Server Details
Verifiable document intelligence for AI agents. Extract, summarize, claim-check, and notarize PDFs & URLs with cryptographic proofs, cross-document search, and on-chain attestation via Base L2.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 20 of 20 tools scored.
Each tool has a clearly distinct purpose with detailed usage descriptions. For example, extract_text vs extract_url vs extract_tables are well-separated, and ask_collection vs search_collection vs qa_url are differentiated by scope and output type.
All tool names follow a consistent verb_noun pattern in snake_case, such as create_collection, extract_text, verify_bundle. The naming is predictable and makes tool roles immediately clear.
With 20 tools, the server covers a broad document processing domain (extraction, summarization, search, claims, notarization). While slightly above the ideal 3-15 range, each tool serves a specific function and the count feels justified.
The tool surface covers the full ingestion-to-query pipeline for documents, including OCR, extraction, collections, Q&A, and verification. Minor gaps exist (e.g., no delete/update for collections or bundles), but the core workflows are fully supported.
Available Tools
20 toolsadd_document_to_collectionAIdempotentInspect
Add an evidence bundle to a collection and trigger async vector indexing. Use after create_collection to populate a collection with documents. Once indexed, documents become searchable via search_collection and ask_collection. Indexing is async — poll get_job_status with the returned job_id until status is "complete". PREREQUISITE: Bundle must have status "complete" (check with get_bundle). Collection must be owned by your API key. Returns: { collection_id, bundle_id, job_id (poll for indexing completion) } Example prompts:
"Add my contract bundle ev_550e8400 to the Q4 Contracts collection."
"Put this evidence bundle into my Due Diligence Docs collection for search."
"Add document [bundle_id] to collection [col_id] with a title."
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional display title for the document in this collection. Example: "Q4 2025 Financial Report" | |
| bundle_id | Yes | Evidence bundle ID (ev_...) to add. Bundle must have status "complete". Example: "ev_550e8400-e29b-41d4-a716-446655440000" | |
| collection_id | Yes | Collection ID (col_...) returned by create_collection. Example: "col_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true), the description discloses async indexing, prerequisite status checks, and the need to poll for completion. This adds significant behavioral context that annotations alone do not cover. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence outlining the main action, followed by context, prerequisites, return value, and examples. It is slightly verbose but informative, with front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async indexing, prerequisites, return value), the description covers all needed aspects: prerequisites, async behavior with polling instructions, and the return object. No output schema exists, but return values are described. The examples further clarify usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for each parameter. The description adds example prompts and format hints (e.g., ev_..., col_...) but does not introduce new semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an evidence bundle to a collection and triggers async vector indexing. It uses specific verbs and resources, and the context around indexing and polling distinguishes it from sibling tools like create_collection, search_collection, and ask_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use after create_collection and lists prerequisites: bundle must have status 'complete' and collection must be owned by the API key. It also explains that indexing is async and to poll get_job_status, providing clear when-to-use and how to handle the async nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ask_collectionARead-onlyIdempotentInspect
Answer a question using RAG over a document collection. Retrieves relevant chunks then synthesizes a cited answer with source attribution. Use when you need a direct answer grounded in your collection documents. For raw matching chunks (without synthesis), use search_collection instead. For single-document Q&A, use qa_url instead. PREREQUISITE: Collection must be populated via add_document_to_collection and indexed before results appear. Returns: { answer: string, sources: [{ bundle_id, chunk_id }], retrieval: [{ bundle_id, chunk_id, text, score }] } Example prompts:
"What are the key terms of the service agreement in my collection?"
"Based on my due diligence docs, what are the main risks?"
"Answer this question using all documents in the Q4 Contracts collection."
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | Natural language question to answer from collection documents. Example: "What are the key terms of the service agreement?" | |
| max_chunks | No | Max chunks to retrieve for context (default 8). Increase for broad questions, decrease for precision. Example: 12 | |
| collection_id | Yes | Collection ID (col_...) returned by create_collection. Example: "col_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description details the retrieval-then-synthesis process with source attribution. It lists the exact return format (answer, sources, retrieval) which is critical since no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, behavior, usage guidance, prerequisite, return format, and examples. Every sentence is necessary and information-dense, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides the full return structure and covers every essential aspect: purpose, when to use, prerequisites, behavioral details, and realistic examples. This makes it highly complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all parameters with examples (100% coverage). The description adds value through example prompts that illustrate appropriate question phrasing, but does not elaborate on max_chunks or collection_id beyond the schema. This additional context elevates it above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Answer a question using RAG over a document collection' and explains it retrieves chunks then synthesizes a cited answer. It explicitly distinguishes from 'search_collection' (raw chunks) and 'qa_url' (single-document Q&A), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says 'Use when you need a direct answer grounded in your collection documents,' and provides clear alternatives for other cases. The prerequisite ('Collection must be populated via add_document_to_collection and indexed') ensures proper context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_claimsARead-onlyIdempotentInspect
Verify a list of factual claims against document text. Uses a quality AI model with citation-level evidence. Use after extract_text or extract_url when you need to validate specific factual assertions. For open-ended questions about a document, use qa_url instead. For multi-document investigation, use ask_collection. Typical workflow: extract_text/extract_url → check_claims. Returns: { claims: [{ claim, status: "supported"|"contradicted"|"not_found", evidence: { quote, paragraphs[] }, confidence: "high"|"medium"|"low" }], truncated: boolean } Example prompts:
"Check whether this contract mentions a liability cap of $1M."
"Verify these claims against the document: [claims list]."
"Does the report actually say revenue grew 23%?"
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Document text to check claims against. Obtain via extract_text or extract_url. Example: "ACME Corp was founded in 2010. Revenue exceeded $1M in 2024." | |
| claims | Yes | Factual statements to verify. Each claim is checked independently against the text. Example: ["Founded in 2010", "Revenue exceeded $1M"] | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Default ~3000 tokens. Truncates input text, not the output. Example: 4000 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds that it uses a 'quality AI model with citation-level evidence', details output structure (status, evidence, confidence), and mentions truncation via max_tokens. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive. Two sentences for purpose/usage, then workflow, output structure, and examples. Front-loaded with key info, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and complexity of verifying claims, the description is complete: covers input, output structure, workflow, and examples. All necessary context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds examples for text and claims parameters, and explains max_tokens as input length cap. Provides value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Verify a list of factual claims against document text.' It uses a specific verb (verify) and resource (claims), and distinguishes from sibling tools qa_url and ask_collection by specifying use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('after extract_text or extract_url') and when not to ('For open-ended questions about a document, use qa_url instead. For multi-document investigation, use ask_collection'). Provides typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_collectionAInspect
Create a named document collection for cross-document semantic search and RAG-based Q&A. Free — no credits consumed. Use when you want to group related evidence bundles for unified search (search_collection) or question answering (ask_collection). NOTE: Collections start empty. Add evidence bundles with add_document_to_collection. Indexing is async — once complete, use search_collection or ask_collection. Returns: { collection_id: string (col_...), name: string } Example prompts:
"Create a collection called Q4 Contracts for my quarterly reports."
"Set up a new document group named Due Diligence Docs."
"Make a collection to organize my vendor agreements."
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable collection name. Example: "Q4 Contracts" or "Due Diligence Docs" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so description carries burden. It adds significant behavioral context: free (no credits), async indexing, collections start empty, and the flow to add documents. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured: purpose first, then cost, usage guidance, important note (empty + async), return format, and example prompts. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description fully covers purpose, lifecycle (empty, add documents, async indexing), return format, and usage examples. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and describes the 'name' parameter well. Description does not add additional meaning beyond the schema's description and examples, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a named document collection for cross-document semantic search and RAG Q&A, with specific verb and resource. It distinguishes from siblings by mentioning the need to add documents afterward and using search/ask tools separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when you want to group related evidence bundles for unified search or question answering' and provides context for when to use siblings like search_collection. Does not explicitly exclude cases but gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
extract_structuredARead-onlyIdempotentInspect
Extract typed fields from document text using a caller-defined schema. Uses a quality AI model with retry logic. Use when you need specific data points from a document rather than full text. For invoices with known fields, parse_invoice (prebuilt schema) may be simpler. For general summarization, use summarize_document instead. Schema format: { "field_name": "type hint or description" } — e.g. { "contract_date": "ISO date", "party_a": "string", "penalty_usd": "number" }. Returns: { data: { : value }, data_cited: { : { value, confidence: "high"|"medium"|"low", citations: [{ quote, paragraphs[] }] } } } Example prompts:
"Extract the contract date, parties, and penalty amount from this agreement."
"Pull the vendor name, PO number, and total from this document."
"Get me all named fields from this form using my custom schema."
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Document text to extract from. Obtain via extract_text or extract_url. Example: "This Service Agreement is entered into on 2025-03-15 between ACME Corp and Beta Inc..." | |
| schema | Yes | Field map: describe each field you want extracted with a type hint. Example: { "total_usd": "number", "vendor": "string", "invoice_date": "ISO date YYYY-MM-DD" } | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Default ~2500 tokens. Truncates input, not output. Example: 3000 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds that it uses a 'quality AI model with retry logic' and explains max_tokens truncates input, not output. Provides return format details. No contradictions. Could mention potential limitations like token caps or confidence handling, but current info is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise and well-structured: purpose, usage guidance, schema format, return format, example prompts. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: input parameters fully described, return format provided (even without output schema), usage context with sibling differentiation, example prompts. Complete for a structured extraction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds context: text should come from extract_text or extract_url, schema format with example, max_tokens behavior. This supplements the schema descriptions well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Extract typed fields from document text using a caller-defined schema', which is a specific verb+resource combination. Distinguishes from siblings by mentioning parse_invoice (prebuilt schema) and summarize_document (general summarization).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when you need specific data points from a document rather than full text.' Also provides alternatives: parse_invoice for invoices with known fields, summarize_document for general summarization. Gives clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
extract_tablesARead-onlyIdempotentInspect
Extract tables and forms as Markdown from a PDF or image (base64-encoded). Use when the document contains structured tabular data such as financial statements, data sheets, or forms. For plain prose documents, use extract_text instead. Returns: { pages: number, text: string } — text contains Markdown-formatted tables. Example prompts:
"Extract the tables from this financial statement."
"Pull the data table from this PDF into Markdown format."
"Get the tabular data from this form document."
| Name | Required | Description | Default |
|---|---|---|---|
| mime_type | Yes | MIME type of the document. Example: "application/pdf" for PDF bank statements, "image/jpeg" for photo of a form. | |
| document_base64 | Yes | Base64-encoded PDF or image bytes (max ~15 MB). Example: "JVBERi0xLjcNJeLjz9MNCj..." (truncated PDF base64) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint and idempotentHint annotations, such as the maximum input size (~15 MB) and the output format (pages, text with Markdown). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core functionality, and includes example prompts without unnecessary verbosity. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description clearly explains the return structure (pages, text with Markdown). The context signals (2 required params, siblings) and the description together provide complete guidance for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions. The description adds practical examples (e.g., mime_type values) and a maximum size constraint not present in the schema, enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts tables and forms as Markdown from PDF or image (base64-encoded). It distinguishes itself from extract_text by specifying it is for structured tabular data, while extract_text is for plain prose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (for structured tabular data like financial statements) and when not to (plain prose documents, directing to extract_text). Includes example prompts that illustrate typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
extract_textARead-onlyIdempotentInspect
Extract plain text from a PDF or image (base64-encoded). Use when you need raw text for downstream AI analysis (summarization, claim checking, structured extraction). For documents at a public URL, use extract_url instead (no base64 encoding needed). Returns: { pages: number, text: string } Example prompts:
"Extract the text from this scanned contract so I can search it."
"Give me the raw text from this PDF document."
"OCR this image and return the text content."
| Name | Required | Description | Default |
|---|---|---|---|
| mime_type | Yes | MIME type of the document. Example: "application/pdf" for PDFs, "image/png" for PNG screenshots. | |
| document_base64 | Yes | Base64-encoded PDF or image bytes (max ~15 MB). Example: "JVBERi0xLjcNJeLjz9MNCj..." (truncated PDF base64) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by disclosing the return format ({ pages: number, text: string }) and providing example prompts, which helps the agent understand what to expect. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and front-loaded: purpose, usage guidelines, return format, examples. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description provides the return structure ({ pages: number, text: string }). It covers purpose, usage alternatives, parameter context (base64-encoded), and examples. For a 2-parameter tool, this is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (mime_type with enum and description, document_base64 with description). The description does not add significant new parameter semantics beyond what is in the schema; it merely repeats that documents are base64-encoded. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Extract plain text from a PDF or image (base64-encoded).' It specifies the verb (extract), resource (text from PDF/image), and distinguishes from siblings like extract_url and extract_structured.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when you need raw text for downstream AI analysis...' and provides an alternative: 'For documents at a public URL, use extract_url instead (no base64 encoding needed).' This gives clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
extract_urlARead-onlyInspect
Fetch a public HTTPS URL and return extracted text and page metadata. Lean mode — no evidence bundle stored, no bundle_id returned. Use for raw text extraction from web pages and online documents. Use summarize_url for summaries, qa_url for Q&A, translate_url for translation, extract_text for base64 file uploads. Returns: { url, title, word_count, text, final_url (after redirects) } Example prompts:
"Extract the text from https://example.com/report.pdf for me."
"Get me the raw content of this web page: [URL]."
"Pull the text from this online article so I can analyze it."
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public HTTPS URL to fetch and extract. Example: "https://example.com/report.pdf" or "https://blog.example.com/article" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds valuable behavioral context: 'Lean mode' (no persistence), mentions no bundle_id returned, and notes that final_url indicates redirect handling. It does not cover all edge cases (e.g., errors), but adds significant transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, key behavior, alternatives, return format, and example prompts. It is concise but covers necessary information without being overly verbose. A slight trim could improve, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (1 param, no output schema), the description is complete. It explains what is returned (url, title, word_count, text, final_url), the lean mode, and essential usage context. No major gaps for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter (url) with format and examples. The tool description repeats the example context but does not add new syntactic or behavioral detail beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch a public HTTPS URL and return extracted text and page metadata') and the resource (URL). It distinguishes from siblings by naming specific alternatives (summarize_url, qa_url, translate_url, extract_text), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Lean mode — no evidence bundle stored') and specifies alternatives for different tasks (e.g., use summarize_url for summaries). This provides clear guidance on selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_bundleARead-onlyIdempotentInspect
Retrieve metadata for an evidence bundle (ev_...) owned by your API key. Free — no credits consumed. Use for quick status/metadata lookups such as checking if a bundle is complete, finding its notarization status, or viewing retention/legal hold info. For deep cryptographic integrity verification (hash + signature + artifact checks), use verify_bundle instead. Returns: { bundle_id, source_url, mode, status: "pending"|"complete"|"failed", manifest_sha256, manifest_signature, signer_address, attestation_tx, attestation_at, eas_uid, parent_bundle_id, superseded_by, legal_hold: boolean, retention_until, created_at } Example prompts:
"Show me the metadata for bundle ev_550e8400."
"Check the status and notarization info of my evidence bundle."
"Get me the details of bundle [ev_id] — is it complete?"
| Name | Required | Description | Default |
|---|---|---|---|
| bundle_id | Yes | Evidence bundle ID (ev_...) returned by extract or notarize_bundle. Example: "ev_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds value by noting it's free, no credits consumed, and owned by the API key. It also lists return fields, providing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: core purpose first, then cost, use cases, alternative, return fields, examples. Each sentence adds value, though slightly long for a simple tool; still earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explicitly lists all return fields. With one clear parameter and a focused purpose, the description is fully complete for selecting and invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a good description. The description reinforces the parameter's format (ev_...) and provides an example, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve metadata for an evidence bundle (ev_...)' and distinguishes from the sibling 'verify_bundle' by specifying that this tool is for quick status/metadata lookups, not deep verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (quick status/metadata lookups) and when not to use (deep verification) with a direct alternative: 'For deep cryptographic integrity verification... use verify_bundle instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_job_statusARead-onlyIdempotentInspect
Poll the status of an async job (extract, indexing, batch). Free — no credits consumed. Use after add_document_to_collection or async extract to check when processing completes. Poll this endpoint in a loop until status is "complete" or "failed". Completed jobs include the bundle_id or result_json in the response. Jobs are created when you POST /v1/extract with a webhook, or when add_document_to_collection triggers async indexing. Returns: { id, type: "extract"|"extract_batch"|"index_collection", status: "queued"|"processing"|"complete"|"failed"|"cancelled", progress_pct: number (0–100), progress_message, bundle_id (when complete), result_json (when complete), error (when failed), created_at, completed_at } Example prompts:
"Check the status of my indexing job job_550e8400."
"Is my async extract job done yet?"
"Poll job [job_id] — what is the current progress?"
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID (job_...) returned by async extract or add_document_to_collection. Example: "job_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint) are reinforced and extended: description explains no credits consumed, how jobs are created, and the full response structure including conditional fields. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with main action, includes necessary details and examples. Slightly verbose but each sentence adds value; example prompts could be summarized but are helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description provides a complete response format with types and conditions. Covers lifecycle from creation to completion, and handles errors. Fully adequate for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (job_id) with schema coverage 100% and clear description in schema. Description does not add new meaning beyond schema and examples, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Poll the status of an async job' with specific resource types (extract, indexing, batch). Differentiates from sibling tools like add_document_to_collection by being a polling function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (after add_document_to_collection or async extract), how to poll in a loop until complete/failed, and notes it's free. Includes example prompts for practical context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_quotaARead-onlyIdempotentInspect
Get current credit balance and plan details for your API key. Free — no credits consumed. Check this before running credit-consuming operations (extract, summarize, etc.) to avoid QUOTA_EXCEEDED errors. Returns plan tier, billing period, and usage breakdown. Returns: { plan_id, billing_period (YYYY-MM), credits_used, credits_limit, credits_remaining, status: "active"|"suspended" } Example prompts:
"How many credits do I have left this month?"
"Check my current quota and plan status."
"Am I going to hit my credit limit soon?"
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description notes the tool is free and consumes no credits, which is additional behavioral info beyond annotations (readOnlyHint, idempotentHint). No contradictions. Could mention idempotency explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise but includes return format and example prompts, which add value. Could be slightly more terse, but structure is clear and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and no output schema, the description fully covers behavior, return format, and usage guidance. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline 4 is appropriate. Schema coverage is 100% and description adds no parameter info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves credit balance and plan details. Verb 'Get' and resource 'quota' are specific and unambiguous. Distinguishes from siblings by being the only quota-related tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before credit-consuming operations to avoid QUOTA_EXCEEDED errors. Includes example prompts. Does not explicitly mention when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_collectionsARead-onlyIdempotentInspect
List all document collections owned by your API key. Free — no credits consumed. Use before search_collection or ask_collection when you need the collection ID. Supports pagination with limit and offset. Returns: { collections: [{ id, name, created_at }] } Example prompts:
"List all my document collections."
"Show me the collections I have created."
"What collections do I own? List them."
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max collections to return (default 50, max 100). Example: 20 | |
| offset | No | Pagination offset (default 0). Example: 0 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: it consumes no credits ('free'), returns a specific JSON structure, and supports pagination. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the key purpose, and includes essential details (cost, usage guidance, return format, example prompts) without unnecessary text. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with strong annotations, the description covers purpose, when to use, parameters, return format, and free cost. No missing information for effective agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for limit and offset. Description mentions pagination but does not add new meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all document collections owned by your API key'), specifies the resource ('document collections'), and includes ownership scope. It differentiates from siblings like search_collection by noting it provides collection IDs needed for other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before search_collection or ask_collection when needing a collection ID, and mentions pagination support. Provides clear context for when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notarize_bundleAIdempotentInspect
Notarize an evidence bundle on-chain by writing its manifest SHA-256 to the blockchain (Base/EVM). Creates a permanent, tamper-evident on-chain record of the document fingerprint. If the bundle is already notarized, returns the existing attestation immediately (idempotent). Use when you need an immutable on-chain timestamp proving a document existed at a point in time. For quick integrity checks without on-chain cost, use verify_bundle instead. PREREQUISITE: Bundle status must be "complete". Check status with get_bundle first. NOTE: Costs gas (ETH). The on-chain record is permanent and cannot be deleted even if the bundle is later purged. Returns: { bundle_id, attestation: { tx_hash, network, attested_at, key_id, eas_uid?, schema_uid? } } Example prompts:
"Notarize bundle ev_550e8400 on-chain so I have a permanent record."
"Put the fingerprint of my evidence bundle on the blockchain."
"Create an on-chain timestamp for this document bundle."
| Name | Required | Description | Default |
|---|---|---|---|
| bundle_id | Yes | Evidence bundle ID (ev_...) to notarize. Bundle must have status "complete". Example: "ev_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and non-destructive behavior. The description enhances transparency by noting idempotency explicitly, mentioning gas cost (ETH), and stating that the on-chain record is permanent and cannot be deleted. These are valuable behavioral traits beyond annotations, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. It front-loads the main action, then covers idempotency, usage guidelines, prerequisite, gas cost, return format, and example prompts in a logical order. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description provides a detailed return format including bundle_id and attestation fields. It also covers prerequisites, idempotency, gas cost, and permanence. For a single-parameter tool, this is exceptionally complete and leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description reinforces the prerequisite and gives an example, but does not add significant semantic information beyond what the schema already provides ('Evidence bundle ID (ev_...) to notarize. Bundle must have status "complete".'). Thus, it is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: notarizing an evidence bundle on-chain by writing its SHA-256 to the blockchain. It distinguishes from sibling 'verify_bundle' by specifying this tool is for permanent on-chain timestamping, not quick integrity checks. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('when you need an immutable on-chain timestamp') and when not to ('for quick integrity checks without on-chain cost, use verify_bundle instead'). It also states a prerequisite (bundle must be 'complete') and advises checking with get_bundle first, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
parse_invoiceARead-onlyIdempotentInspect
Parse a receipt or invoice document into structured fields. Uses a quality AI model for accuracy. Use when you need to extract line items, totals, and merchant info from financial documents. For general document text, use extract_text instead. Returns: { invoice: { merchant, date (YYYY-MM-DD), line_items[], subtotal, tax, total }, cited: { : { value, confidence: "high"|"medium"|"low", citations: [{ quote, paragraphs[] }] } } } Example prompts:
"Parse this invoice and give me the line items and total."
"Extract the merchant, date, and amounts from this receipt."
"Read this scanned invoice and return structured data."
| Name | Required | Description | Default |
|---|---|---|---|
| mime_type | Yes | MIME type of the document. Example: "application/pdf" for scanned invoice PDF, "image/jpeg" for a receipt photo. | |
| document_base64 | Yes | Base64-encoded PDF or image of the receipt/invoice (max ~15 MB). Example: "JVBERi0xLjcNJeLjz9MNCj..." (base64-encoded invoice PDF) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying use of a 'quality AI model for accuracy' and detailing the return structure with confidence levels and citations, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, usage guidance, return format, and example prompts. It is concise yet informative, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description compensates by fully detailing the return structure (invoice fields, cited fields with confidence and citations). For a two-parameter tool, this provides complete context for proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. The tool description does not add additional semantics or constraints for the parameters beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool parses receipt/invoice documents into structured fields, listing specific extractions (line items, totals, merchant info). It distinguishes from the sibling 'extract_text' by specifying financial documents vs general text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('extract line items, totals, and merchant info from financial documents') and when not to use ('For general document text, use extract_text instead'), providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
qa_urlARead-onlyInspect
Fetch a public HTTPS URL and answer a specific question about its content. Lean mode — no bundle stored. Use when you have a precise question about a web page. For a broad summary, use summarize_url. For multi-document Q&A, use ask_collection instead. Returns: { url, answer, answer_cited: { value, confidence, citations[] }, confidence: "high"|"medium"|"low", truncated } Example prompts:
"What is the refund policy at https://docs.example.com/policy?"
"Look at [URL] and tell me what the delivery terms are."
"Answer this question based on the content of [URL]: [question]."
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public HTTPS URL to fetch and question. Example: "https://docs.example.com/policy" | |
| question | Yes | Specific question to answer from the page content. Example: "What is the refund policy?" | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Truncates fetched page content, not the answer. Example: 4000 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. Description adds behavioral details: 'Lean mode — no bundle stored', truncation behavior via max_tokens, and return format including confidence and citations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured: purpose first, then usage guidance, return format, and examples. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description provides partial return format and covers key aspects. Could mention error handling, but sufficient given high schema coverage and sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds meaningful context: explains max_tokens as 'Input length cap (1 token ≈ 4 chars)' and provides example values for url and question parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a public HTTPS URL and answers a specific question about its content. It uses specific verbs 'Fetch' and 'answer' and distinguishes itself from siblings like summarize_url and ask_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when you have a precise question about a web page' and provides alternatives: 'For a broad summary, use summarize_url. For multi-document Q&A, use ask_collection instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_collectionARead-onlyIdempotentInspect
Semantic (vector) search across documents in a collection. Returns ranked text chunks with relevance scores. Free — no credits consumed. Use when you need raw matching chunks from a collection. For a synthesized cited answer from the same context, use ask_collection instead. PREREQUISITE: Collection must be populated via add_document_to_collection and async indexing must complete (poll get_job_status) before results appear. Returns: { results: [{ bundle_id, chunk_id, text, score: number (0–1), title? }] } Example prompts:
"Search my Q4 Contracts collection for mentions of liability cap."
"Find the clause about data retention in my due diligence docs."
"Search for revenue numbers across my quarterly reports."
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max chunks to return (default 10, max 50). Example: 5 | |
| query | Yes | Natural language search query. Example: "What were the revenue numbers for Q4?" | |
| collection_id | Yes | Collection ID (col_...) returned by create_collection. Example: "col_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds that the tool is free, requires async indexing, and provides the return format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: starts with purpose, then key features, usage distinction, prerequisites, return format, and examples. It is slightly verbose but every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description includes the full return structure, prerequisites, async behavior, and example prompts. It covers all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions. The description adds example values and clarifies that 'query' expects natural language, providing additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs semantic search across documents in a collection, returning ranked text chunks. It distinguishes itself from the sibling 'ask_collection' by specifying it provides raw chunks rather than synthesized answers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (for raw matching chunks) and when not to (use ask_collection for cited answers). It also lists the prerequisite that the collection must be populated and indexing must complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
summarize_documentARead-onlyIdempotentInspect
Summarize document text into a prose summary and key points with citations. Use after extract_text or extract_url when you need a condensed understanding of a long document. For single-sentence Q&A, use qa_url instead. For extracting specific fields, use extract_structured. Typical workflow: extract_text/extract_url → summarize_document. Returns: { summary: string, key_points: string[], summary_cited: { value, confidence, citations[] }, key_points_cited: [{ text, citations[] }], truncated: boolean, strategy: "full"|"truncated"|"chunked" } Example prompts:
"Summarize this financial report and give me the key points."
"What are the main takeaways from this document?"
"Give me a concise summary of this 50-page report."
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Document text to summarize. Obtain via extract_text or extract_url. Example: "The Q4 2025 financial report shows revenue growth of 23% year-over-year..." | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Default ~3000 tokens. Truncates input, not output. Example: 4000 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds details about truncation and strategies, but no need for destructive warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact yet comprehensive: includes purpose, usage, workflow, return format, and examples with no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: input, output structure, workflow integration, and example prompts. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds context on how to obtain the text parameter and explains max_tokens input behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it summarizes document text into prose summary and key points. Distinguishes from siblings like qa_url and extract_structured.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use after extract_text/extract_url, and provides alternatives for single-sentence Q&A or structured extraction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
summarize_urlARead-onlyInspect
Fetch a public HTTPS URL and return a prose summary with key points. Lean mode — no bundle stored. Use when you need a condensed understanding of a web page. For raw text, use extract_url. For asking a specific question about a page, use qa_url. Returns: { url, summary, key_points: string[], truncated: boolean, word_count } Example prompts:
"Summarize https://en.wikipedia.org/wiki/Artificial_intelligence for me."
"Give me the key points from this blog post: [URL]."
"What is this article about? Summarize [URL]."
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public HTTPS URL to fetch and summarize. Example: "https://en.wikipedia.org/wiki/Artificial_intelligence" | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Truncates fetched page content, not the output summary. Example: 4000 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. The description adds behavioral context: 'Lean mode — no bundle stored' and mentions truncation via the return field 'truncated'. Does not cover auth or rate limits, but sufficient given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured: first sentence states purpose, next sentence adds context, then alternative tools, then return fields, then examples. Could be slightly more concise, but overall well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description lists return fields (url, summary, key_points, truncated, word_count). Includes example prompts. Lacks detail on max_tokens behavior and truncation mechanism, but still sufficiently complete for a 2-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond schema; it mentions 'public HTTPS URL' but that's inferred from schema. Example prompts show usage but not parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Fetch a public HTTPS URL and return a prose summary with key points.' It explicitly distinguishes from sibling tools (extract_url, qa_url) by mentioning alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use ('use when you need a condensed understanding of a web page') and when not to use ('For raw text, use extract_url. For asking a specific question about a page, use qa_url'). Also notes 'Lean mode — no bundle stored'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
translate_urlARead-onlyInspect
Fetch a public HTTPS URL and return its content translated into a target language. Lean mode — no bundle stored. Use when you need to understand web content in a different language. For extracting raw untranslated text, use extract_url instead. Returns: { url, translated_text, target_lang, truncated } Example prompts:
"Translate https://example.de/artikel into English for me."
"Translate this German article into Spanish: [URL]."
"Fetch [URL] and give me the French translation."
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public HTTPS URL to fetch and translate. Example: "https://example.de/artikel" | |
| max_tokens | No | Input length cap (1 token ≈ 4 chars). Truncates fetched page content before translation. Example: 4000 | |
| target_lang | Yes | ISO 639-1 language code for the target language. Example: "es" for Spanish, "fr" for French, "de" for German, "ja" for Japanese, "zh" for Chinese |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by stating 'Lean mode — no bundle stored' (stateless operation) and describes the return structure including truncation via max_tokens. No contradiction with annotations (readOnlyHint: true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the core purpose. It uses short sentences, includes examples, and avoids unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, usage, behavioral traits, and provides examples. The annotations and schema support completeness, making it sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage and already describes all three parameters adequately. The description does not add significant new semantics beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool fetches a public HTTPS URL and returns its content translated into a target language. It uses a specific verb ('Fetch and return') and distinguishes itself from the sibling tool extract_url, which extracts raw untranslated text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when you need to understand web content in a different language' and directs using extract_url for raw untranslated text, providing clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_bundleARead-onlyIdempotentInspect
Verify the cryptographic integrity of an evidence bundle (ev_...) owned by your API key. Checks manifest hash, EIP-191 signature, and R2 artifact hashes. Free — no credits consumed. Use when you need to confirm a bundle has not been tampered with. For quick metadata lookups (without full crypto verification), use get_bundle instead. Returns: { valid: boolean, bundle_id, manifest_sha256, checks: { status, manifest_hash, signature, artifacts: [{ name, ok }] }, tampered: string[], signer_address: string|null, attestation_tx: string|null, url: string, captured_at: string } Example prompts:
"Verify the cryptographic integrity of bundle ev_550e8400."
"Is this evidence bundle still valid and untampered?"
"Deep-check the manifest hash and signature of my bundle."
| Name | Required | Description | Default |
|---|---|---|---|
| bundle_id | Yes | Evidence bundle ID (ev_...) returned by extract or notarize. Example: "ev_550e8400-e29b-41d4-a716-446655440000" |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safety and reproducibility. Description adds return structure, lists checks, and details what happens (crypto verification), fully disclosing behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: main action first, then details, then sibling reference, then return format, then examples. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though no output schema, the description provides complete return structure. With one parameter, clear usage guidance, and example prompts, the description covers all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of the single parameter with a clear description. Description does not add new parameter semantics but provides example prompts and context about ownership by API key, slightly enhancing usability beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Purpose is explicitly stated: cryptographic integrity verification of an evidence bundle. Distinguishes from sibling tool get_bundle by specifying its lighter role. Includes specific checks (manifest hash, EIP-191 signature, R2 artifact hashes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states when to use ('confirm a bundle has not been tampered with') and when not to use ('for quick metadata lookups, use get_bundle instead'). Also notes it's free and consumes no credits, providing additional decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!