Unstructured document processing for LLM pipelines. Upload as PDF/DOCX/TXT any supported files, extract structured data (PII-redacted), build LLM-ready datasets, and search/export results — all via MCP tools (document.process, job.status, job.result, dataset.build, dataset.search, dataset.export).
Package extracted records into a dataset for export (Step 4).
Triggers an async dataset build from a completed execution. Returns a job_id
immediately — poll with job.status until status='completed'. The completed
response includes dataset_id, which you pass to dataset.export to retrieve all
records as text. This step is required before calling dataset.export.
Args:
execution_id: Execution ID from a completed data_process job
(from job.status or job.result).
name: Dataset name. Auto-generated from the source filename if omitted.
description: Optional description for this dataset.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| description | No | ||
| execution_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| job_id | No | |
| status | No | |
| isError | No | |
| poll_hint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key behavioral trait that annotations do not: the operation is asynchronous. It states that it returns a job_id immediately, that job.status must be polled until 'completed', and that the completed response contains dataset_id. It also notes the prerequisite of a completed execution, adding meaningful behavioral context beyond the sparse annotation hints.
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 succinct yet information-dense. The one-line purpose is followed by a compact workflow sentence and a clear Arg list. Every sentence adds necessary context, and the most important usage constraint is 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?
The description covers the async lifecycle, required inputs, optional parameters, dependency on prior execution, and downstream use with dataset.export. Since an output schema exists, the description does not need to enumerate return fields, and it provides the necessary integration details to call 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?
With 0% schema description coverage, the description fully compensates. It explains execution_id as coming from a completed data_process job via job.status or job.result, name as auto-generated from the source filename when omitted, and description as optional. This gives an agent semantic understanding the schema alone lacks.
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 opens with a specific verb-plus-resource statement: 'Package extracted records into a dataset for export (Step 4).' It clearly identifies the tool's role in the pipeline and distinguishes it from siblings like dataset.export and dataset.search by positioning it as the build step required before export.
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 explains exactly when to use the tool: after a completed execution, before dataset.export. It also provides the full workflow: triggers async build, returns job_id, poll job.status until completed, then pass dataset_id to dataset.export. This is explicit usage guidance with sequential context, leaving little ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve LangChain/LlamaIndex-ready text chunks from an indexed dataset (Pro+ plan).
Returns paginated RAG chunks. Each chunk includes text, token count, and metadata
(quality grade, PII masking status, document type, language). Use FlexOrchRetriever
or FlexOrchReader from the flexorch-sdk for automatic pagination.
The dataset must be indexed first via dataset.index(dataset_id).
Args:
dataset_id: ID of the indexed dataset.
min_quality: Minimum quality grade to include: A, B, C, or D. Default: B.
Chunks with grade at or above this threshold are returned.
Example: "B" returns grade A and B chunks.
pii_masked_only: When true, return only chunks where PII was masked. Default: false.
page: Page number, 1-indexed. Default: 1.
page_size: Chunks per page, max 100. Default: 20.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| dataset_id | Yes | ||
| min_quality | No | B | |
| pii_masked_only | No |
| Name | Required | Description |
|---|---|---|
| page | No | |
| error | No | |
| total | No | |
| chunks | No | |
| isError | No | |
| has_more | No | |
| page_size | No | |
| dataset_id | No | |
| chunk_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds useful behavioral context: pagination behavior, the requirement that the dataset must be indexed first, and the quality threshold semantics. It discloses what the returned chunks include (text, token count, metadata fields) and the Pro+ plan limitation. It doesn't describe pagination limits beyond page_size max, but overall it goes beyond annotations without contradicting them.
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 short overview paragraph, a prerequisite note, and a clear Args list. Every sentence adds value: the return payload summary, the SDK pagination pointer, and the indexing prerequisite are all useful. It is slightly long but the density of relevant information justifies its length.
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 read-only, paginated listing tool, the description covers the key operational details: prerequisite (indexing), pagination behavior, response contents, and parameter semantics. It has an output schema available to explain return values, so the description need not detail them. Missing minor details like error cases or auth requirements, but these are largely covered by the overall context and the tool's read-only nature.
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 0%, so the description carries the full burden of explaining parameters. It explains min_quality threshold semantics with a concrete example ('B' returns A and B), clarifies pii_masked_only meaning, notes page is 1-indexed, and specifies page_size max is 100. Only dataset_id is minimally described ('ID of the indexed dataset'), but the description compensates for the schema's total lack of description.
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 states a specific verb ('Retrieve'), a resource ('text chunks from an indexed dataset'), and an application context ('LangChain/LlamaIndex-ready'). It clearly distinguishes from siblings like dataset.search by focusing on paginated chunk retrieval rather than search or indexing.
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 states when to use this tool: after the dataset has been indexed via dataset.index(dataset_id), and it mentions using FlexOrchRetriever/FlexOrchReader from the flexorch-sdk for automatic pagination. It gives clear context for the indexed-dataset prerequisite, which distinguishes it from dataset.index and dataset.build.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download all records from a built dataset as text (Step 5 — final step).
Returns the complete dataset content as a UTF-8 string directly in the response —
no file download or separate URL needed. Call get_job_status after build_dataset
and wait for status='completed' before calling this tool. Use the dataset_id from
that completed response.
Format guide: jsonl = LLM fine-tuning, rag = LangChain/LlamaIndex chunks,
csv = spreadsheets, md = human-readable, xml = structured interchange.
Binary formats (parquet, hf) cannot be returned via MCP — export them from
the FlexOrch dashboard directly.
Args:
dataset_id: Dataset ID from the get_job_status completed build response.
format: Text export format — jsonl, csv, json, md, xml, rag. Default: jsonl.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | jsonl | |
| dataset_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| format | No | |
| content | No | |
| isError | No | |
| filename | No | |
| byte_count | No | |
| dataset_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds valuable context beyond this: the response is a UTF-8 string returned directly in the response, no file download or separate URL is involved, and binary formats cannot be returned via MCP.
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 and front-loaded with the core purpose. Sections for return behavior, usage sequence, format guide, and parameters all add value without redundancy or filler.
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 two-parameter tool with an output schema, the description is fully complete: it covers prerequisites, workflow order, format selection, return type, and known limitations. An agent has everything needed to invoke the tool correctly and interpret the result.
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 0%, so the description carries the full burden for parameter meaning. It explains dataset_id as coming from a completed get_job_status response and enumerates the text formats with their intended use cases, which is far more useful than the raw 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 downloads all records from a built dataset as text and identifies it as Step 5, the final step. This distinguishes it from siblings like dataset.build, dataset.chunks, and dataset.search.
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 describes the required sequence: call get_job_status after build_dataset, wait for status='completed', then use the returned dataset_id. It also explains which format to choose per use case and directs users to the dashboard for binary formats that MCP cannot return.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger semantic indexing for a dataset — required before using dataset.chunks (Pro+ plan).
Starts an async indexing job that splits the dataset into RAG-ready text chunks,
generates embeddings, and stores them for semantic search. Indexing is idempotent:
calling it again on an already-indexed dataset re-indexes with fresh embeddings.
Indexing typically completes in 10–60 seconds depending on dataset size.
After indexing, use dataset.chunks(dataset_id) to retrieve the text chunks.
Args:
dataset_id: ID of the built dataset to index (from job.status after dataset.build).
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| isError | No | |
| message | No | |
| dataset_id | No | |
| index_hint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description substantially exceeds the annotations by disclosing that indexing is asynchronous, splits data into RAG-ready chunks, generates embeddings, stores them, is idempotent but re-indexes with fresh embeddings, and typically completes in 10–60 seconds. It also notes the Pro+ plan requirement and the correct retrieval method afterward. No contradiction with annotations 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 front-loaded with the primary action and requirement, then provides concise behavioral details, timing expectations, and parameter guidance. Every sentence adds value, and the Args section cleanly closes the description without 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?
For a single-parameter async indexing tool, the description covers the full workflow: prerequisite (dataset.build), downstream use (dataset.chunks), behavior (chunking, embeddings, storage), idempotency, timing, and plan requirement. An output schema exists, so not detailing return values is acceptable. The context is complete for safe and 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?
With 0% schema description coverage, the description fully compensates by explaining dataset_id as 'ID of the built dataset to index' and gives provenance: 'from job.status after dataset.build'. This tells the agent where to obtain the value, which is more useful than the schema's bare integer type and title.
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 opens with a specific verb and resource: 'Trigger semantic indexing for a dataset'. It clearly distinguishes this from siblings by stating it is 'required before using dataset.chunks' and that indexing prepares a dataset for semantic search. The scope—indexing a built dataset for RAG—is 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 gives clear workflow context: index 'required before using dataset.chunks' and the dataset_id comes 'from job.status after dataset.build'. It does not explicitly state when not to use it or compare it with alternatives like dataset.search or dataset.export, but the prerequisite and downstream steps are clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all indexed FlexOrch datasets by keyword or meaning.
Use this to find specific documents or records without processing a new file.
Requires at least one dataset to exist. Structured search works on all plans.
Semantic and hybrid modes require a Pro plan — a clear upgrade message is returned
if the plan is insufficient. mode='auto' picks structured on free plans, hybrid on Pro+.
Args:
query: Search query — natural language or keyword. Max 1000 characters.
top_k: Number of results to return. Default: 5, max: 50.
mode: Search strategy — auto (default), structured, semantic, hybrid.
semantic and hybrid require Pro plan.
document_type: Filter to a specific document type, e.g. invoice (optional).
language: Filter by document language, ISO 639-1 code, e.g. en, de, tr (optional).
quality_grade: Filter by quality grade: A, B, C, or D (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | auto | |
| query | Yes | ||
| top_k | No | ||
| language | No | ||
| document_type | No | ||
| quality_grade | No |
| Name | Required | Description |
|---|---|---|
| mode | No | |
| error | No | |
| query | No | |
| isError | No | |
| results | No | |
| total_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the readOnly/idempotent annotations: it explains plan-gated modes, the upgrade message, the auto-mode resolution logic between free and Pro plans, and the dataset existence requirement. These are non-obvious behaviors an agent needs to know before invoking.
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: a clear one-sentence purpose, followed by usage context and plan behavior, then a compact Args list. Every sentence contributes necessary operational detail, and the most important behavioral nuances are front-loaded before the parameter details.
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?
The tool has six parameters, plan-dependent behavior, and a required precondition; the description covers all of these, including the error/upgrade path. The presence of an output schema means return-value documentation is not required here, and nothing essential to correctly calling the tool is missing.
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 0%, but the Args block fully compensates by explaining every parameter: query length limit, top_k default and max, mode options with plan requirements, document_type example, language format with ISO 639-1 examples, and quality_grade allowed values. This is far more informative than the raw 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 opens with a specific verb and resource: 'Search across all indexed FlexOrch datasets by keyword or meaning.' It clearly distinguishes itself from siblings by emphasizing search over already-indexed data and explicitly contrasting with 'without processing a new file.'
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 states when to use the tool: 'Use this to find specific documents or records without processing a new file.' It also provides a precondition ('Requires at least one dataset to exist') and plan-based guidance for mode selection. However, it does not explicitly name alternative sibling tools or state when not to use it beyond the 'without processing' implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a document for processing — this is always the first step (Step 1 of 5).
Downloads the file from file_url, then submits it to FlexOrch for automatic
classification, structured field extraction, PII detection/masking, and quality
scoring. Processing is asynchronous — this tool returns immediately with a
job_id. You MUST call job.status(job_id) every 3–5 seconds until
status='completed' before calling job.result.
Args:
file_url: Publicly accessible URL of the document (http/https only, max 50 MB).
Supported: PDF, DOCX, TXT, XLSX, HTML, XML, EML, JPG, PNG, TIFF.
mask_pii: Replace detected PII (names, IDs, emails, phone numbers) with
[MASKED_TYPE] placeholders in all output. Default: true.
document_type: Optional classification hint — FlexOrch auto-detects if omitted.
Values: invoice, expense_report, purchase_order,
sales_proposal, bank_statement, payroll.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | Yes | ||
| mask_pii | No | ||
| document_type | No | auto |
| Name | Required | Description |
|---|---|---|
| error | No | |
| job_id | No | |
| status | No | |
| isError | No | |
| poll_hint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, idempotentHint=false), so the description carries the burden — and it delivers: it discloses async behavior (returns immediately with job_id), a REQUIRED polling protocol with cadence, file constraints (http/https, 50 MB, supported formats), and the masking default. These are exactly the non-obvious behaviors that would trip an agent.
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?
Each paragraph earns its place: purpose and step position up front, then pipeline mechanics, then the mandatory async protocol, then parameter docs required by the 0% schem coverage. No rdundncy; the most actionable information (polling cadence, call ordering) is 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?
Complete for a complex async tool: pipeline stages, job_id return, explicit next-step workflow, parameter semantics, and file constraints are all covered. An output schema exists so crediting return details is correctly left to it; the only trivial gap is that document_type's value list omits the 'auto' default from the schem.
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 0% (only titles and defaults), so the description fully compensates: it annotates the meaning of each param, the URL access and size/sformat constraints for file_url, the [MASKED_TYPE] placeholder behavior for mask_pii, and the auto-detection fallback plus value list for document_type. It adds meaning far beyond the schem.
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?
States a specific verb and resource ('Submit a document for processing') and anchors it as Step 1 of 5, immediately separating it from mid- and post-processing siblings like job.status and document.reprocess. The pipeline description (classification, extraction, PII masking, quality scoring) makes the tool's function 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?
Gives clear when-to-use context: this is always the first step, and spells out the mandatory follow-on flow of polling job.status every 3–5 seconds before job.result. However, it never names exclusions or an alternative for already-processed documents (document.reprocess), leaving the when-not-to-use case implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-queue an already-uploaded document through the pipeline.
Use this to re-run extraction/PII detection/quality scoring on a document you've
already processed — e.g. after a document_type_hint change, without downloading and
re-uploading the original file. Returns immediately with a job_id — poll with
job.status the same way as after document.process.
Only works for documents whose original file is still stored on the server (locally
uploaded, not connector-sourced). If the file is no longer available, re-upload it
with document.process instead.
Args:
document_id: ID of a previously processed document.
pipeline_config: Optional pipeline config overrides, e.g. {"document_type_hint": "invoice"}.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| pipeline_config | No |
| Name | Required | Description |
|---|---|---|
| error | No | |
| job_id | No | |
| status | No | |
| isError | No | |
| poll_hint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the asynchronous behavior (returns immediately with a job_id), the polling mechanism, and the storage-dependent failure mode. These behavioral details go well beyond the sparse annotations and give the agent accurate expectations about side effects and follow-up calls.
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 front-loaded with the core action, then covers usage scenario, constraints, fallback, and return behavior in a tight sequence. The Args list is minimal and each sentence adds essential 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?
For a tool with a simple two-parameter schema but async behavior and preconditions, the description covers invocation, response pattern, limitations, and alternative routing. The output schema exists, so not detailing the return payload is acceptable.
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 0%, so the description carries all parameter meaning. It clarifies document_id as a previously processed document ID and explains pipeline_config as optional overrides with a concrete JSON example, fully compensating for the bare 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 opens with a specific verb+resource ('Re-queue an already-uploaded document through the pipeline') and clearly scopes the action to reprocessing existing documents. It also distinguishes itself from document.process by positioning reprocess as the follow-up for already-processed documents.
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 when-to-use context (after a document_type_hint change, avoiding download/re-upload), a hard precondition (original file must still be stored; connector-sourced docs excluded), and a named alternative fallback (re-upload with document.process). Also tells the agent to poll with job.status after the immediate job_id return.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read structured fields extracted from a completed document (Step 3).
Use the execution_id from a completed data_process job (job.status response).
Returns document type, detected language, quality grade (A–D), PII summary,
column list, and extracted field values. If no dataset has been built yet, the
response includes a fields_hint guiding you to call dataset.build next.
To retrieve all rows as a file, proceed to dataset.build → dataset.export.
Note: Masked fields appear as [MASKED_TYPE] placeholders — raw PII is never returned.
Note: execution_id comes from data_process jobs only; dataset_build jobs use dataset_id.
Args:
execution_id: Execution ID from the job.status completed response.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| fields | No | |
| columns | No | |
| isError | No | |
| privacy | No | |
| quality | No | |
| degraded | No | |
| has_more | No | |
| row_count | No | |
| document_id | No | |
| fields_hint | No | |
| execution_id | No | |
| document_type | No | |
| has_more_hint | No | |
| detected_language | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent, and the description adds meaningful behavioral detail: masked PII placeholders are never raw, the response may include a fields_hint when no dataset has been built, and execution_id is restricted to data_process jobs. These details help the agent predict responses and downstream actions beyond the schema.
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 longer but each sentence adds workflow or behavioral value. It is front-loaded with the core purpose, followed by usage notes and parameter clarification. Minor redundancy exists between the 'Use the execution_id...' sentence and the later note about execution_id provenance, but the structure remains clear and scannable.
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 single-parameter read tool with an output schema, the description covers the essential context: what data comes back, what happens when no dataset has been built, how to get rows as a file, and which job types are valid. Nothing an agent needs to call this tool correctly or route to related tools is missing.
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 0%, but the description's Args section defines execution_id as 'Execution ID from the job.status completed response.' This adds necessary provenance semantics on top of the bare integer type. It also clarifies the execution_id vs dataset_id distinction, which is important for correct invocation.
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 a specific verb and resource: 'Read structured fields extracted from a completed document (Step 3).' It clearly identifies what the tool returns and distinguishes it from dataset.* and document.* siblings by framing it as a job-result/read step. The Step 3 positioning helps an agent place it in the workflow without ambiguity.
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 explicitly tells the agent where to get execution_id: from a completed data_process job's job.status response. It also gives exclusions and alternatives: dataset_build jobs use dataset_id, and to retrieve all rows as a file the agent should proceed to dataset.build → dataset.export. This is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a job until it finishes — call this after document.process or dataset.build (Step 2).
Call repeatedly every 3–5 seconds until status is 'completed' or 'failed'.
For data_process jobs: the completed response includes execution_id — pass it to
job.result. For dataset_build jobs: the completed response includes
dataset_id — pass it to dataset.export.
Args:
job_id: Job ID returned by document.process or dataset.build.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| stage | No | |
| job_id | No | |
| reason | No | |
| status | No | |
| isError | No | |
| degraded | No | |
| pii_count | No | |
| pii_found | No | |
| poll_hint | No | |
| row_count | No | |
| dataset_id | No | |
| pii_masked | No | |
| document_id | No | |
| has_dataset | No | |
| dataset_name | No | |
| execution_id | No | |
| quality_grade | No | |
| quality_score | No | |
| pii_type_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral details beyond those: polling cadence, terminal status values, and the presence of execution_id or dataset_id in the completed response. This informs the agent what to expect and how to proceed without contradicting the 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 compact and well-organized: main purpose first, then polling behavior, then downstream routing, then the argument. Every sentence adds useful information, and the Args section is cleanly separated.
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 single-parameter polling tool with an output schema and readOnly/idempotent annotations, the description covers all necessary operational guidance: when to call, how to poll, terminal states, and what to do with the result. No critical context is missing.
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 schema only documents job_id as an integer, but the description adds critical provenance by stating it is 'returned by document.process or dataset.build'. This compensates for the 0% schema description coverage, though the explanation is brief and does not elaborate on validation or edge cases.
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 states a specific action—poll a job until it finishes—and identifies the exact triggering operations (document.process, dataset.build). It clearly separates this tool from the sibling job.result by explaining that job.result consumes data from the completed job status response.
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 call this tool ('after document.process or dataset.build'), how often to poll ('every 3–5 seconds'), and when to stop ('until status is 'completed' or 'failed''). It also routes downstream usage to job.result and dataset.export based on job type, giving 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
dataset.builddataset.chunksdataset.exportdataset.indexdataset.searchdocument.processdocument.reprocessjob.resultjob.statusClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
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
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
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.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Each tool maps cleanly to a distinct pipeline stage or resource: document submission, reprocessing, job polling, result retrieval, dataset build, export, index, search, and chunk retrieval. Even the similar document.process and document.reprocess are clearly separated by whether a new file is involved or an existing stored document is re-queued.
Most tools follow a consistent noun.action dot-namespace pattern like document.process, dataset.build, and job.status. dataset.chunks and job.result deviate by using nouns rather than action verbs, and one description references get_job_status/build_dataset instead of the actual tool names, creating minor inconsistency.
Nine tools is well within the ideal range and each tool earns its place in the document processing and dataset export lifecycle. There are no redundant or filler tools, and the count matches the complexity of the workflow.
The full documented pipeline is covered: submit, poll, read results, build dataset, export, index, search, and retrieve chunks, with reprocessing available as an alternative to re-upload. No described workflow step dead-ends, and optional RAG features are supported through dataset.index and dataset.chunks.