docs: align public contracts with URL-only document parsing - #1
Merged
Conversation
The Gateway removed document.upload and made document.parsing accept HTTPS URL input only, but the public docs still documented the upload session flow. Following them produced 404 TOOL_NOT_FOUND on /v1/tools/document.upload/call and INVALID_ARGUMENTS for uploadId. - Drop document_upload / document.upload from both README tables and document the required fileUrl + fileName body. - Rewrite the document-parsing Skill and Tool Reference around URL-only input, including the HTTPS, length, and no-userinfo constraints. - Delete scripts/upload_document.py; the service side no longer exists. - Correct the endpoint count from 24 to 23, matching the live catalog and the OpenAPI ToolID enum. Co-Authored-By: Claude <noreply@anthropic.com>
…drift The public docs described the happy path only, so integrators had no authoritative list of failure codes, no request size limits, and no statement of how restricted keys and metered Tools behave. - Add contract sections to both READMEs: the 12 stable error codes with their HTTP mapping, the two API key access modes, the special handling of account/usage Tools and document.result.get, idempotency semantics and header names per protocol, request body limits, and the three metered Tools with their units and caps. - Document the GET /v1/tools response shape. - List the valid usage.history service filter values and the protocol values in the account-usage Tool Reference. - Add .github/catalog.json, a snapshot of the live capability contract, and extend validate_skills.py to reject any documented Tool ID, MCP Tool, or MCP endpoint missing from it. This is what would have caught the document.upload drift automatically. Co-Authored-By: Claude <noreply@anthropic.com>
The abbreviated example used empty objects for input_schema and output_schema, which hid the fact that discovery returns complete JSON Schemas. Fill in a real input schema, note that name is the MCP Tool name, and mark the elided output schema explicitly. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Gateway removed
document.uploadand switcheddocument.parsingto HTTPS-URL-only input, but this repository still documented the upload-session flow. Anyone following the published docs hit hard failures:POST /v1/tools/document.upload/call→404 TOOL_NOT_FOUNDdocument_parsing {"uploadId":"..."}→400 INVALID_ARGUMENTSThe endpoint count was also stale (24 vs. the 23 Tools the service actually exposes).
What changed
Correctness (the breaking part)
document_upload/document.uploadfrom both README tables;document_parsingnow shows the real body{"fileUrl":"…","fileName":"…"}.document-parsingSkill and Tool Reference around URL-only input, including the HTTPS / 1,024-character / must-have-host / no-userinfo constraints and the explicit list of rejected input forms.skills/document-parsing/scripts/upload_document.py— the service-side capability it drove no longer exists.Completeness
document.result.get, idempotency semantics and per-protocol header names, request body limits, and the three metered Tools with units and caps.GET /v1/toolsresponse shape.usage.historyservicefilter values andprotocolvalues.Unit prices are deliberately not published here; the docs say they are provided with the API key.
Drift prevention
.github/catalog.json, a snapshot of the live capability contract (verified field-by-field against the Gateway'sapi/mcp-tools.json: 9 endpoints, 23 Tools, all matching).validate_skills.pyto fail when any Markdown file mentions a Tool ID, MCP Tool name, or/mcp/*endpoint that is absent from the snapshot.This last part is the root-cause fix. The previous validator only checked frontmatter and directory names, which is why the
document_uploadremoval went unnoticed.Verification
python .github/scripts/validate_skills.pypasses.document_upload,document.upload, and/mcp/document-uploadinto the README makes the validator fail on all three; removing them restores a pass.ToolIDenum.🤖 Generated with Claude Code