netcafe-docs

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

Annotations already declare read-only/idempotent behavior. The description adds valuable behavioral context beyond annotations: polling interval, status handling ('done'/'error'), and the role of retry_after_seconds/next_action. It doesn't fully describe error edge cases or rate limits, but it exceeds the baseline with meaningful operational detail.

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?

Two dense, information-rich sentences with a helpful example. Every sentence earns its place, front-loads purpose, and then gives usage behavior. 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 having an output schema (which handles return value specifics), the description covers the full usage cycle: how to poll, what to look for, how to handle wait vs. completion, and where to find the job_id. For a polling tool with one parameter, this is complete and self-sufficient.

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 provides 100% coverage with a clear description of job_id ('returned when the task was started'). The description reinforces this by mentioning 'id-from-a-job-tool', but adds little semantic value beyond the 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 states a specific verb ('Get the status or result') and a clear resource ('a job started by deep_research, translate_pdf, or make_slides'). It distinguishes from sibling tools by naming the job-starting tools and clarifies it is for polling. The example URL adds specificity.

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?

Explicit guidance is provided: poll every 15-30 seconds, follow retry_after_seconds and next_action while pending, and prefer structured_result when complete. This tells the agent exactly when and how to use the tool versus alternatives, even including a URL example.

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 already convey the read-only, idempotent, and non-destructive nature. The description adds behavioral detail about how the tool analyzes parsing issues and returns actionable fixes, and the W3C validator analogy gives a concrete mental model. It does not contradict annotations, and there are no hidden side effects mentioned.

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—two sentences that front-load the core action, detail the checks performed, and describe the output. Every sentence earns its place, using the W3C validator analogy for quick comprehension. No fluff or 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 tool with a single parameter and an output schema, the description covers the purpose, input constraints, method, and output type. It is complete enough for an agent to correctly select and invoke the tool without additional context. The sibling tools are clearly different in scope.

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 fully describes the only parameter (url) with its type and accepted formats. The description does not add significant new parameter-specific semantics beyond what the schema provides. With 100% schema coverage, the 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 tool checks resumes for ATS compatibility, listing specific checks (text extractability, email/phone/sections, multi-column layouts, tables, emoji). It is distinguished from sibling tools by focusing on resumes and using the W3C validator analogy, 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?

The description implies when to use the tool: when a resume needs ATS parsing validation. It provides clear context about the input (PDF/.docx URL) and the type of output (score and fixes). However, it does not explicitly mention alternatives or exclusions, such as when to use check_job 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?

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds that it returns a hosted PDF download URL and uses headless Chromium via Gotenberg, providing useful implementation context 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 two concise sentences plus an example. Every sentence adds value: core functionality, return format, and a concrete invocation example. No fluff or redundant content.

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 2-parameter tool with rich annotations and an output schema, the description covers input types, output format, and example invocation. It omits potential edge cases like URL accessibility requirements, but this is acceptable given the high contextual coverage from annotations and schema.

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 descriptions cover both parameters fully (100% coverage), so the baseline is 3. The description reinforces 'URL or raw HTML' but does not add format constraints or edge-case behavior beyond what the schema already provides.

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 'Convert a web page or HTML to PDF' with a specific verb and resource, then clarifies 'Print-quality PDF from a URL or raw HTML via self-hosted Gotenberg'. This clearly differentiates it from sibling conversion tools like pdf_to_markdown, which reverse the direction.

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 implies usage through the example GET request and the phrase 'via self-hosted Gotenberg', but it does not explicitly state alternatives or when-not-to-use. The context is clear enough for an agent to select this tool for HTML-to-PDF needs.

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 already declare readOnlyHint, idempotentHint, and destructiveHint:false, so the safety profile is clear. The description adds valuable behavioral context by specifying input format requirements and the output's purpose (importable by QuickBooks). 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 two sentences, front-loaded with the core action, and every sentence contributes: first states the conversion, second gives input requirements and a sibling pairing. 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?

With good annotations, an output schema, and 100% schema coverage, the description covers the essential purpose, input constraints, and relationship to extract_statement. A minor gap is not clarifying that either csv or url must be provided, but overall the context is sufficient for an AI agent to select and invoke the 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 the baseline is 3. The description adds meaning by clarifying that the CSV must contain date, description, and amount (or debit+credit) columns, which directly informs how to use the 'csv' parameter. This goes beyond the schema's 'CSV content with a header row.'

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 ('Convert'), a clear resource ('transaction CSV'), and a distinct output ('.qbo / OFX bank-feed file'), making the tool's purpose immediately obvious. It also distinguishes from siblings by explicitly pairing with extract_statement (PDF input to bank feed output).

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 provides clear context by stating the required CSV columns ('date, description and amount columns (or debit + credit)') and mentions the complementary sibling tool extract_statement. However, it does not explicitly state when not to use this tool or list alternative tools for CSV conversion, 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?

The description discloses key behavioral traits beyond the annotations (which are all false): it is asynchronous ('Returns a job_id immediately'), takes 2-5 minutes, and is a multi-step process (plans, searches, reads, writes). It also mentions the underlying system (gpt-researcher, AI NetCafé). It does not mention potential failures or rate limits, but for this tool the disclosed context is substantial.

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 packed with useful information and is front-loaded with purpose. Each sentence serves a function: behavior, workflow, usage guidance, and example. The mention of '29k stars' is mildly extraneous for an AI agent, but it does not detract significantly; it could be trimmed without losing critical guidance.

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 asynchronous nature, 2 parameters, an output schema, and sibling check_job, the description covers the full workflow: what it does, how long it takes, what it returns immediately, how to follow up, and when to use it. The example ties everything together, making it complete for a tool of this 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 coverage is 100% for both parameters, so the baseline is 3. The description adds extra value by instructing to phrase the topic as a question rather than a keyword, and by providing a concrete example. The depth parameter is well-explained in the schema and the description's example reinforces the default.

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 strong verb+resource: 'Start an autonomous web research task.' It clearly distinguishes this from sibling tools like check_job by explaining it initiates a research process and returns a job_id immediately. The phrase 'real research, not a single model call' further clarifies its unique scope.

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?

Explicit guidance is given: 'Use this when you need sourced, current information rather than what a model already knows.' It also tells the agent to poll check_job for the result, naming the specific alternative/follow-up tool. This gives clear when-to-use and what-to-do-next context.

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 (read-only, idempotent, non-destructive), the description reveals valuable behavioral traits: the reconciliation cross-check formula, the output formats (JSON + CSV), and the exact failure feedback (difference and row where running balance breaks). This gives the agent a strong grasp of what to expect.

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?

Two sentences: the first states the primary action and output, the second details the reconciliation check and failure reporting, followed by a clear limitation. Every sentence contributes, and the key info 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?

With one parameter, robust annotations, and an output schema present, the description covers the necessary context: the input, the processing logic, the return behavior, and an explicit limitation. There are no significant gaps for agent selection and 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 schema already fully describes the only parameter (`url` with description). The description adds minimal extra meaning—only implying the URL must point to a text-layer PDF—but the baseline of 3 is appropriate given the high schema coverage.

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 uses a specific verb ('Turn... into') and names the exact resource: 'a bank statement or transaction PDF'. It clearly distinguishes from sibling tools like extract_tables by focusing on bank-specific reconciliation rather than generic table 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?

It implicitly tells when to use: for bank statements requiring a reconciled transaction table, and explicitly states the constraint 'Text-layer PDFs only (scanned images not yet supported)' as a when-not. However, it doesn't explicitly name alternatives for scanned PDFs or generic table extraction.

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, non-destructive), the description adds valuable behavioral traits: 'Rows the model was unsure about are flagged rather than guessed' and the limitation 'Text-layer PDFs only.' This gives insight into output quality and compatibility without contradicting 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 three sentences, front-loaded with the core function, followed by the fields explanation, then constraints and behavioral note. Every sentence adds value with no redundancy or 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?

For a tool with two parameters and an existing output schema, the description covers purpose, parameter usage, limitations, and uncertainty handling. It is complete enough for an agent to invoke the tool correctly without additional context.

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 covers both parameters with 100% coverage, so the baseline is 3. The description adds some context for the fields parameter by explaining its purpose (aligning differently-named headers), but does not introduce new syntax or format details 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 the tool extracts tables from a PDF into structured rows (JSON + CSV), specifying the resource (PDF) and output format. It distinguishes from siblings like pdf_to_markdown or extract_statement by emphasizing structured tabular data and the option to force a fixed column 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?

The description provides clear context on when to use the tool, especially for aligning documents with inconsistent headers by passing fields. It also sets a constraint with 'Text-layer PDFs only,' implying it should not be used for scanned/image PDFs, but it does not explicitly name alternative tools.

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?

The description discloses the transformation behavior (detect, repair, re-emit) beyond what annotations provide. It also indicates the output format (UTF-8 with BOM). Annotations already declare read-only and non-destructive, so the description adds meaningful context about the specific processing steps.

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 two sentences, front-loaded with the core action, and every part adds value: encoding types, mojibake examples, and the BOM detail. No filler or redundant 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?

The description covers the main functionality and expected input/output. It does not mention that one of two parameters must be supplied, nor does it clarify asynchronous behavior (sibling check_job suggests possible job-based execution), but the output schema exists and the core behavior is well-explained.

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 both 'url' and 'text' described, so the baseline is 3. The description implies these are two alternative input methods ('Detect... and re-emit' doesn't add new parameter meaning), but it doesn't clarify that at least one is needed. No additional semantic value is added 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 the tool's function: detect real encoding, repair mojibake, and re-emit UTF-8 with BOM. The verb 'repair' and specific resource 'CSV' make it distinct from sibling tools, which are largely PDF-related.

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 title and description provide clear context: use when a CSV opens garbled in Excel. It doesn't explicitly mention alternatives or exclusions, but the use case is unambiguous. Since there are no closely related CSV tools (except csv_to_qbo, which serves a different purpose), this is sufficient.

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?

Despite all annotations being false, the description discloses key behavioral traits: it is asynchronous (returns a job_id, poll check_job), has a typical latency (1-3 minutes), and ensures a real file output rather than a web editor link. It also names the underlying service (Presenton) and hosting, adding trust and operational context.

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 front-loaded with the core value proposition. It packs essential information (async behavior, expected time, example) into three sentences with no filler or 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?

Given the tool's moderate complexity (async flow, polling dependency), the description adequately covers the workflow via the example and mention of check_job. An output schema exists, so explicit return-value details are not required. Minor gaps like error handling or rate limits exist but are not critical given the output schema and clear polling pattern.

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 baseline is 3. The description does not add much parameter-specific detail beyond what the schema already provides; the example shows usage of 'topic' and 'slides' but does not explain formats, defaults, or constraints 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 the tool's function: turning a topic or outline into a downloadable .pptx file, explicitly distinguishing it from a web editor link. The verb 'turn' and resource '.pptx file' are specific, and the contrast with 'not a link' adds precision.

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 implies when to use (when you need a generated PowerPoint deck) and gives an example call, but it does not explicitly name alternatives or exclusions among sibling tools. It provides context about async polling but stops short of clear usage boundaries.

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 already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate these. It adds template syntax and feature options, but does not disclose processing behavior such as asynchronous execution or how the output file is returned. Since output schema exists, this is not a major gap, but it limits the score.

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 three sentences long, each serving a clear purpose: stating the action, listing capabilities, and providing a template example. No fluff, and the most critical information appears first.

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 7 parameters, output schema, and annotations present, the description covers the core functionality and template syntax. It could mention whether the operation is asynchronous or returns a job ID (given check_job sibling), but the output schema likely covers return values. Overall, it is sufficiently complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete template example ('Page {n} of {total}') and enumerating supported options that map to parameters (start_at, style, skip_first, etc.), enhancing understanding 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 opens with 'Stamp page numbers or footer text onto every page of a PDF,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like pdf_to_markdown or redact_text. It also skims through main features, reinforcing the tool's purpose.

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 states 'the combination Acrobat cannot do without scripting,' which gives context on when to use this tool. However, it does not explicitly name alternatives or 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavior beyond annotations: exact text-layer extraction, vision model for images, cost differences, and reading order handling. It exceeds the baseline and does not contradict any annotation.

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?

Two tightly written sentences. The first sentence states the core action and scope, the second clarifies behavior and cost. No filler or repetition, and the most important information 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?

Given an output schema exists and annotations are present, the description covers input types, formatting preservation, multi-column handling, and cost/processing differences. It lacks explicit mention of file size limits or language support, but the provided information is sufficient for most use cases.

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 already defines the single 'url' parameter with 100% coverage and a clear description. The tool description does not add further parameter-specific detail beyond what the schema provides, so it meets the baseline but not more.

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 converts PDFs or scanned images into Markdown with formatting preservation and reading order. The verb 'convert' and specified output make the purpose unambiguous, and it distinguishes itself from sibling tools like extract_tables or translate_pdf.

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 clear context on when to use the tool (for text-layer PDFs vs scanned images) and notes cost differences, but does not explicitly name alternative sibling tools or exclusion criteria. This is more specific than generic guidance but stops short of explicit 'use this instead of X' instructions.

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?

The description reveals deterministic placeholder mapping and the fact that no model sees the input, adding to annotations (readOnlyHint, idempotentHint). It also clarifies the output format with a mapping table.

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 two sentences, front-loaded with the core action and includes only meaningful caveats (determinism, rule-based). 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?

For a tool with an output schema and only two simple params, this description fully covers the purpose, behavior, privacy implications, and determinism. The existence of an output schema means return values are already structured.

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?

Both parameters ('text' and 'only') are already well-described in the schema with 100% coverage. The description does not add additional parameter-specific semantics beyond the general behavior, so the 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 uses the specific verb 'Strip' and lists concrete PII types (emails, phone numbers, API keys), plus states the output (redacted text and mapping table). This clearly differentiates it from sibling tools which are unrelated (e.g., pdf_to_markdown, convert_to_pdf).

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 tells the agent when to use it: 'before sending text on' and emphasizes rule-based operation with no model passing, which guides privacy-sensitive use. It doesn't explicitly exclude alternatives, but none of the siblings are redaction tools.

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 already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context: it uses open-source Whisper, supports 100 languages, is self-hosted, and has a 15 MB limit. No contradictions with annotations, and the extra details go beyond what annotations alone provide.

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 two sentences plus a concrete example. It front-loads the core action and then adds relevant details. Every part earns its place with no filler or 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?

The tool has an output schema, so return values are already covered. The description provides use cases, size limits, and model details, making it fairly complete. It does not mention potential asynchronous behavior or limitations like duration, but these are not necessary given the output schema and the clarity of the operation.

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 baseline is 3. The description does not add significant meaning to the parameters beyond the schema, though the example URL with a parameter placeholder reinforces the required 'url' parameter. The language auto-detect is already mentioned in 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 states a specific verb+resource combination: 'Fetch an audio file from a URL and transcribe it to text.' It clearly distinguishes itself from sibling tools (which are PDF, CSV, and slides tools) by focusing on audio transcription. The addition of Whisper and language support further clarifies the exact scope.

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 provides clear use cases ('voice memos, podcast clips and meeting recordings') and a size constraint ('up to ~15 MB'). It implies when to use this tool but does not explicitly name alternatives or state when not to use it. This is strong contextual guidance, but lacks explicit exclusions.

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?

The description discloses asynchronous behavior (returns job_id, poll check_job), expected latency (20-60 seconds), output formats (translated-only and bilingual), and underlying technology (PDFMathTranslate). This adds significant context beyond the sparse 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 purpose, and includes a concrete example. However, the example contains an incorrect parameter name, which slightly undermines the efficiency and reliability of the 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 a full input schema and an output schema present, the description appropriately explains the async workflow, polling, and output types. It does not need to detail return values. The minor error in the example does not compromise overall completeness but detracts slightly.

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?

While schema coverage is 100% and the schema already documents all parameters, the description's example uses 'target' instead of the actual parameter 'lang_to', which is misleading. This introduces an ambiguity that could cause incorrect tool 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 clearly states the tool's function: 'Translate a PDF from a URL while preserving the original layout' and highlights unique features (formulas, figures, two-column typesetting) that distinguish it from ordinary translators and sibling tools like pdf_to_markdown. The example flow reinforces the purpose.

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 provides clear context on when to use the tool (for layout-preserving PDF translation from a URL) and contrasts it with 'ordinary translators that flatten the document'. However, it does not explicitly specify when not to use it or name alternative tools among the siblings.

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