ImgKits MCP

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

Goes well past the annotations: synchronous execution, 2 credits per call with mcp-credit-gateway charging before forwarding, required Authorization: Bearer sk_live_... header, per-format size limits, and transparency support for image watermarks. These are exactly the operational facts an agent cannot derive from readOnly/destructive/openWorld 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?

Purpose leads, then constraints grouped by mode, then operational notes. Dense but almost every clause carries a constraint; the billing/header sentence is somewhat long and could be tightened.

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 13-parameter tool with no output schema, the description never states what comes back — a hosted URL, base64, or a job reference — beyond 'synchronous' and the echoed idempotency_key. Inputs are thoroughly covered; the successful-call result shape is the notable hole.

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 all 13 parameters are already documented, and the description mostly restates the same ranges (opacity 0.05-1, position list, pages format). It does group the two conditional requirements under their watermark_type branches, which is modest added value over 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?

States a specific verb and resource ('Add a visible ... watermark to an image or PDF') plus the input channel (public URL). The word 'visible' implicitly separates it from the sibling embed_blind_watermark, but no sibling is named explicitly.

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 preconditions for each mode: watermark_type=text needs `text`, watermark_type=image needs `watermark_image_url`, PDF page limiting via `pages`, plus accepted formats and size ceilings. It never says when to prefer this over embed_blind_watermark or remove_watermark, so routing to alternatives remains inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well beyond the annotations by disclosing that processing is asynchronous upstream with internal polling and a ~75 second timeout, that the Worker stores nothing while upstream MinerU data lives ≤24h, and that billing is charged before job creation with no automatic refunds. These are exactly the operational facts an agent needs to set expectations and avoid surprise cost.

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?

Front-loads the purpose, then uses compact labeled blocks (Input, Processing, Storage, Billing) so the agent can scan constraints quickly. The trailing 'Powered by MinerU' attribution and license URL are slightly beyond call-relevant content but are short and not disruptive.

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 input shape, async/timeout behavior, data retention, and billing — a lot for a two-parameter tool with no output schema. The remaining gap is return shape: it never says whether multiple files produce per-file or concatenated Markdown, nor what is returned when the ~75s poll times out mid-job.

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 the baseline is 3, but the description adds real constraints absent from the schema: the 20 MiB per-file cap, the enumerated supported formats (pdf, png, jpeg, webp, bmp, tiff), and the rejection of private/local/metadata hosts. The layout-JSON flag is explained in the schema itself and only lightly echoed here.

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?

Names a specific verb and resource ('Convert PDF and image files to clean Markdown') and states the intended downstream use (RAG, LLM ingestion, knowledge bases). It does not explicitly differentiate itself from siblings like ocr_image or extract_tables, so an agent must infer that this is the full-document Markdown path rather than a text- or table-only extraction.

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 concrete selection context: 1-5 public https URLs, ≤20 MiB, supported formats listed, and an explicit exclusion ('DOCX is not supported in this release', 'Private, local, and metadata hosts are rejected'). What is missing is sibling routing — nothing says when to prefer ocr_image (single image text) or extract_tables (table-only) over this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses the async task path, the default and max wait window, the job_id fallback on timeout, the returned `content` field, and — critically — a cost of 2 credits charged by mcp-credit-gateway before forwarding. That is behavior an agent cannot infer from annotations or 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?

Front-loaded with purpose, then the workflow, then cost — dense and mostly waste-free. The reference to the internal 'AiController CreateDecodeBlindWatermarkTask + GetDecodeBlindWatermarkResult' method names is implementation detail an agent doesn't act on and could be trimmed.

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?

With no output schema, the description correctly covers return values (`content`, `job_id`) and billing, which is what an agent needs to compose a call. It stops short of saying what happens when no watermark is found or the decode fails, a minor but real gap for a task-based 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%, so the baseline is 3; the description earns above baseline by explaining the implicit two-mode contract (`source_url` starts a job vs. `job_id`-only polls) that the schema does not encode as an anyOf/oneOf. It adds no further format detail on `idempotency_key` beyond the schema text.

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 ('Read a blind watermark from an image') plus the accepted input form (public http(s) URL). The read/decode direction is clearly distinguishable from the sibling `embed_blind_watermark`, so an agent can pick the right one without opening a schema.

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 concrete usage rules: start with `source_url`, poll with only `job_id`, and the reassurance that polling never spawns a new upstream task. It does not explicitly name exclusions or alternatives (e.g., when to prefer a non-blind watermark tool), which keeps it at 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well past the annotations by disclosing the mechanism (local Unicode-script + stopword/diacritic heuristic), that no upstream call is made, and the billing model including the COST_DETECT_LANGUAGE flag. Since there is no output schema, naming the returned fields (language code, confidence, reliability flag, alternatives) is genuinely load-bearing information.

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?

Three compact sentences; the core capability and the character limit are front-loaded, followed by mechanism, return shape, and billing in descending priority. The env-var reference is slightly jargon-heavy but earns its place by answering a cost question.

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 read-only tool with no output schema, the description covers input limits, the implementation's accuracy tradeoffs, the returned fields, and cost — everything an agent needs to call it and interpret the result without guessing.

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 both parameters carry their own descriptions, including the accuracy tip and the idempotency_key billing note. The description's length ceiling and billing mention duplicate the schema rather than adding new parameter semantics, so baseline 3 applies.

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?

Opening sentence gives a specific verb and resource (detect the language) plus an explicit input bound (20,000 characters). It is clearly distinguishable from the translate_* siblings, which transform text rather than identify it.

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?

No sentence states when to choose this over alternatives or what the typical workflow is (e.g., call before translate_text to pick a target language). Usage is only implied by the tool's obvious role, so the guidance is adequate but thin.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Beyond the annotations (which only signal a non-readOnly, open-world, non-idempotent, non-destructive call), the description discloses that execution is synchronous, that billing is 2 credits charged by mcp-credit-gateway before forwarding, that embedded content is never echoed back, and that a server-held secret is used when text is omitted. Those are exactly the operational facts an agent cannot infer from structured fields.

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?

A single dense but well-ordered paragraph: operation and input constraints first, then the secret/text branch, then algorithm options, then execution mode and cost. No filler sentences, and every clause carries decision-relevant 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?

With 5 parameters, 100% schema coverage, annotations present and no output schema, the description covers the remaining gaps an agent needs: synchronous behavior, credit cost and who charges it, secret-key fallback, and non-echo of embedded content. Nothing required to invoke it correctly 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 100%, so the schema already explains `model` (DWT vs DCT), `strength` 1-10, size limits and `watermark_text` semantics; the description largely restates these. It adds only marginal context (e.g., strength being optional, DWT as the robust default) beyond the schema, so baseline 3 applies.

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 names a specific verb and resource ("Embed an invisible/blind watermark into an image") plus the input contract (public URL, formats, size). The words "invisible/blind" implicitly distinguish it from the sibling add_watermark (visible overlay) and its inverse decode_blind_watermark, so an agent can route correctly without opening schemas.

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 gives clear operational guidance for the key branching decision: pass `watermark_text` or omit it to use the server-held BLIND_WATERMARK_KEY, with a concrete example (order id). However, it never states when to prefer this tool over add_watermark or that decode_blind_watermark is the verification counterpart, so sibling routing is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations only declare the safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive); the description adds the operationally important traits: asynchronous execution that polls until done or times out near 75 seconds, per-table merged-cell expansion semantics, accuracy caveats for borderless/handwritten tables, no retention of uploads or results, ≤24h upstream retention, and a billing charge placed before the job is created with no refunds.

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 capability and output shape are front-loaded, then constraints, then behavior, then billing – a sensible order. The trailing 'Powered by MinerU' and license-URL lines are attribution rather than agent-relevant guidance, a small amount of non-earning 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?

With only one parameter and no output schema, the description carries the burden well: it names the returned fields (row_count, column_count, page_idx, bbox), discloses async/timeout behavior, states accuracy limits, and covers storage and cost implications. An agent has enough to call it correctly and to set expectations on 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 coverage is 100%, so the baseline is 3, but the description adds call-critical constraints absent from the schema: the 20 MiB per-file cap, the accepted file extensions, and the rejection of private/local/metadata hosts. It adds real meaning on top of 'array of https URIs' rather than restating it.

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 ('Extract tables from PDFs and images') and specifies the exact output shape (HTML plus a row/column matrix), which lets an agent distinguish it from ocr_image or convert_to_markdown by result type. It never names those siblings explicitly, so routing still requires the agent to infer.

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 concrete applicability constraints: 1-5 public https URLs, ≤20 MiB each, a supported format whitelist, rejection of private/local/metadata hosts, and an explicit negative case (DOCX is not supported). It stops short of saying when to prefer a sibling such as convert_to_markdown or ocr_image instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well beyond the annotations: it discloses that processing is asynchronous and this call polls until completion or times out at ~75 seconds, that files/results are not stored while upstream MinerU tasks persist up to 24h, and that billing is charged before the job is created with no automatic refunds. The coordinate-system caveat (content-list coordinates, not character-level, not rescaled to pixels) is exactly the kind of output nuance an agent could otherwise get wrong. Nothing contradicts readOnlyHint=false / openWorldHint=true / idempotentHint=false.

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?

Front-loaded with purpose and return format, then constraints, then side effects, then licensing. Almost every sentence carries unique information; the MinerU license line is low-value for tool selection but short enough not to hurt.

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 one-parameter OCR call with no output schema, the description covers input constraints, return structure including the coordinate caveat and table_cell blocks, async/timeout behavior, retention, and cost. An agent has everything needed to invoke it correctly and predict the response.

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 single required 'files' array, so the baseline is 3. The description still adds real value by specifying per-file size limits, the allowed MIME set, the external-host restriction, and the DOCX exclusion — constraints the schema itself cannot express.

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 first sentence gives a specific verb and resource ('Extract text from images, screenshots, and scanned PDF pages') and the following sentence pins down the exact return shape (blocks with [x0,y0,x1,y1] boxes and page indexes). It does not explicitly contrast itself with siblings like extract_tables or convert_to_markdown, so differentiation is left implicit.

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 hard input conditions (1-5 public https URLs, ≤20 MiB, supported formats, DOCX unsupported, private/local/metadata hosts rejected), which strongly implies when the tool is applicable. However, it never names an alternative tool for the excluded cases (e.g., local files, DOCX, table-only extraction), so an agent must infer routing from the sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well past the annotations by disclosing pricing (3 credits per call), the sk_live_ key requirement, that mcp-credit-gateway charges before forwarding, rate limiting, that every attempt including failures is logged with an audit id, and that bulk misuse may be blocked or reported. These are exactly the operational and consequence details an agent needs before committing to a destructive, non-idempotent call.

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 first half is well front-loaded, but the metering/audit/audit_id information is stated two or three times across the English paragraph, the parenthetical Chinese sentence, and the closing sentence. That redundancy costs space without adding 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 single-image metered mutation with no output schema, the description covers input constraints, mask modes, authorization gates, cost, and the fact that an audit_id comes back. Nothing an agent needs to call it correctly or safely 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 already 100%, so the baseline is 3; the description still adds cross-parameter behavior the schema does not encode — that mask_image_url and mask_rect are alternatives and that omitting both falls back to upstream auto-detect, whose availability is upstream-dependent. It also restates the mask polarity (white = remove) and the 0–1 normalization, though that duplicates 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?

States a specific verb and resource ("AI watermark removal / inpainting") plus hard scope: ONE image, JPG/PNG/WebP, <=10 MB, public URL. An agent can immediately distinguish this from the sibling add_watermark and from the blind-watermark 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?

Gives a strong when-to-use condition (only owned or explicitly licensed/authorized material) and explicit exclusions (no copyright/attribution stripping, no bulk third-party removal). It also explains the mask-mode selection: mask_image_url, mask_rect, or neither for upstream auto-detect. It does not name a sibling tool as an alternative path, which keeps it below 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing the async/polling lifecycle, that upstream deletes temporary and original files, that result URLs expire in ~24 hours, and that each new job costs 5 credits charged before forwarding. These are exactly the consequences an agent needs before calling.

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?

Dense but front-loaded: what it does, formats/limits, async semantics, then retention and cost. Every sentence carries actionable information with no repetition of the title.

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 the lifecycle, cost, and limits for a 7-parameter tool with no output schema, and it does explain that a job_id comes back when the wait elapses. It is slightly thin on what a completed poll returns (e.g. the final result URL field), relying on the expiry sentence to imply it.

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 the baseline is 3; the description adds meaning by framing wait_seconds as the per-call wait inside an async job (default 30, max 120) and clarifying that job_id polling does not create a new translation. Remaining parameters (from, file_name, idempotency_key) are left to 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?

States a specific verb+resource ('Translate a document from a public URL') plus the supported format list, which immediately separates it from translate_text, translate_image, and translate_subtitle in the sibling set.

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 operational context: async job with a wait budget, and explicit instruction to re-call with the same job_id to poll rather than start a new job. It does not explicitly route to siblings (e.g. use translate_text for raw text) or state exclusions, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well beyond the annotations by disclosing async job semantics, the polling contract, the ~24 hour expiry on upstream result URLs, and the 2-credit cost charged by mcp-credit-gateway before forwarding. These are exactly the operational traits an agent needs and none are derivable from readOnlyHint/openWorldHint/idempotentHint alone.

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?

Five tight sentences, front-loaded with the resource scope, then the async contract, then the expiry and cost caveats in descending order of importance. No sentence is redundant.

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?

With no output schema, the description still explains what comes back (job_id when still running, result URLs otherwise) and the expiry risk on those URLs. Combined with the cost note and size limits, an agent has everything needed to call and follow up 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the cross-parameter contract (job_id resumes polling instead of creating a new billable job) and reinforcing the wait_seconds and image size limits. It stops short of clarifying the interaction between 'to'/'from' and a resumed job_id, which would be the remaining ambiguity.

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 ('Translate text inside 1-10 images') plus the input medium (public URLs) and format constraints, which cleanly separates it from translate_text, translate_document, and ocr_image. An agent can identify the tool without opening the schema.

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 strong operational guidance for the async flow: wait up to wait_seconds, poll by re-calling with the same job_id, and that polling does not start a new job. It does not explicitly name the sibling alternative (e.g., translate_text for plain text, translate_document for files), so the when-to-use-vs-alternative dimension is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Adds substantial context beyond the annotations: exact preservation semantics (timestamps, cue order, indices and ASS event fields untouched, only cue text translated), synchronous execution, and a 3-credit cost charged by mcp-credit-gateway before forwarding. This tells the agent about billing side effects and the blast radius of the operation, which the hints (destructiveHint=false, openWorldHint=true) do not convey.

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?

Three short sentences, each carrying distinct load: capability and formats, transformation guarantees, then cost/execution model. Front-loaded with the identifying information and free of 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?

With no output schema, the description still covers input limits, transformation behavior, sync vs async, and billing, which is most of what an agent needs. The one gap is the return shape — whether it returns translated subtitle text, a job handle, or usage metadata — which is left implicit.

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 the baseline is 3, but the description earns a bump by explaining what happens to subtitle_content — timestamps and structural fields are preserved, only cue text is translated — which is semantics the schema cannot express. It does not add anything on 'to'/'from'/'idempotency_key' beyond the schema, keeping it out of 5 territory.

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 (translate subtitle content) plus the exact accepted formats (SRT, WebVTT, ASS/SSA), which cleanly separates it from translate_document, translate_text and translate_image. An agent can route on this line alone.

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 formats imply the use case (you have raw subtitle text), and the 1,000,000-character limit plus the synchronous note give practical context. However, there is no explicit guidance on when to prefer this over translate_document or translate_text, and no exclusion stating that binary/file inputs belong elsewhere.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Goes well beyond the annotations: discloses synchronous execution, automatic chunking at ~1,900 chars, credit cost (1 per call), gateway pre-charge behavior, and required Bearer auth on the endpoint. These are exactly the operational facts an agent needs and cannot get from readOnlyHint/openWorldHint alone.

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?

Six short, information-dense statements with limits and cost front-loaded ahead of operational details. No filler or restatement of the title.

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 scope, limits, cost, and auth thoroughly, which is most of what matters here. There is no output schema and the description never indicates the return shape (e.g., translated strings in input order), leaving a small gap for the 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?

Schema coverage is 100%, so the baseline is 3, but the description adds processing semantics the schema can't convey: how oversized `text` is chunked and that total length across `texts` is capped. It does not elaborate on language-code formats, though the schema examples already cover that.

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 ('translate ... plain text') and scopes it against its siblings implicitly by naming 'plain text' versus translate_document/translate_image/translate_subtitle. The input limits are stated up front, so an agent knows exactly what this call handles.

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 operating context: synchronous, size caps (50,000 chars / 50 strings), and automatic chunking for long inputs. It does not explicitly say 'use translate_document for files' or name an alternative, so routing versus siblings is left to inference from the 'plain text' framing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.