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

With no annotations provided, the description carries the full burden for behavioral disclosure. It states the tool performs a delete operation and returns a confirmation, but lacks details on side effects, permissions, or irreversibility.

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 relatively short and front-loaded with the main action. The inclusion of both English and Persian text adds length but is justified for bilingual context.

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 delete tool with 2 parameters and an output schema, the description covers the endpoint, return type, and instance option. However, it lacks details on document_url sourcing and any error conditions.

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 must add meaning. It explains the optional 'instance' parameter but does not elaborate on the 'document_url' format or where to obtain it, providing only partial context.

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 explicitly states the tool deletes a previously uploaded document and its results, with a clear action verb and resource. It also mentions the API endpoint and return type, distinguishing it from sibling tools that are read-oriented.

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 for deletion but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or limitations.

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 a behavioral trait: 'May start processing any remaining pages of the document.' It also mentions the HTTP method (POST) and return structure. However, since no annotations are provided, the description carries the full burden; it does not cover authentication needs, rate limits, or potential errors.

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 in English plus a Persian translation and additional notes. It front-loads the main purpose but includes redundancy (Persian translation) and could be more concise. The structure is acceptable but not optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, no enums, no nested objects), the description covers the core functionality and return fields. However, it lacks explanation of error conditions, prerequisites (e.g., document must exist), and details about the processing side effect. With an output schema present, the return value listing is adequate.

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 must explain both parameters. It only explains the optional 'instance' parameter ('Optional name... Omit to use the default instance'). The required 'document_url' parameter is not described beyond being the document identifier; its format or constraints are omitted.

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 'Fetch full detail for a document' and enumerates the returned fields (thumbnails, page URLs, pages, type). This is a specific verb+resource. However, it does not differentiate from sibling tools like 'alefba_read_document' or 'alefba_document_pages', which may have overlapping functionality.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it compares to other document-related tools in 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?

With no annotations provided, the description fully carries the transparency burden. It discloses the HTTP method (POST), endpoint, and exact return structure ({document_url, pages}). However, it does not explicitly state if the operation is read-only or non-destructive, though the context implies it.

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 (3 sentences) and front-loaded with the primary purpose. The bilingual addition (English/Persian) is relevant and does not detract. Slightly longer than necessary but still efficient.

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 presence of an output schema (context signals indicate 'Has output schema: true'), the description need not detail return values. It adds useful context about the API endpoint and instance selection. For a simple list operation, this is 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?

Schema coverage is 0%, so the description must explain parameters. It clarifies that document_url is the document identifier and instance is optional (defaults to default). However, it does not specify the expected format of document_url or how instances are configured.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('list the page URLs') and the resource ('previously uploaded document'). It also distinguishes from sibling tools by specifying the exact output (collection of page URLs) and HTTP endpoint.

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 guidance on when to use this tool versus siblings like alefba_read_document or alefba_document_status. The description only explains the instance parameter but lacks context for tool selection.

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?

No annotations provided, so description carries burden. States API endpoint and return shape, but does not disclose if operation is read-only or has side effects. 'Report' implies idempotent read, but not explicit.

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, bilingual, front-loaded with purpose. Some redundancy in Persian text, but efficient overall.

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?

Describes endpoint, parameters, and return mapping. Output schema exists, reducing need to detail return values. Missing error handling or rate limits, but adequate for async progress tracking.

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 has 0% description coverage, but description adds meaning: 'instance' is optional and defaults to default instance; 'document_urls' is for one or more documents. Explains behavior beyond schema types.

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?

Clear verb ('report') and resource ('processing progress for one or more documents'). Specifies return mapping for tracking async jobs, distinguishing it from sibling tools like alefba_read_document or alefba_download_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?

Implicitly suggests use for tracking async jobs, but no explicit guidance on when to use versus alternatives (e.g., alefba_read_document for final results). No when-not-to-use or exclusion criteria.

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?

With no annotations, the description discloses key behaviors: it calls POST /api/download_excel/, returns download info or saved path when save_path is provided, and requires prior processing for Excel output. It does not cover error handling or permissions, but the provided details are adequate.

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 fairly concise but includes a duplicate Persian translation which adds unnecessary length for an English-speaking agent. The structure is logical: purpose, precondition, return info, instance guidance. Removing the Persian line would improve conciseness.

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 (3 parameters, has output schema), the description covers the essential aspects: what it does, when to use it, return behavior, and parameter semantics. It lacks examples or error scenarios but is reasonably complete for a download 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 coverage is 0%, so the description must clarify parameters. It effectively describes the document_url as the document to download, save_path as an optional local path, and instance as the Alefba instance target. This adds meaning beyond the basic types and titles 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 clearly states the tool's purpose: downloading an analyzed document as an Excel (.xlsx) file. It specifies the API endpoint and distinguishes itself from sibling tools like alefba_download_pdf, alefba_download_word, etc., by focusing on Excel 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 context by stating the precondition: 'The document must have been processed with type=excel.' It also explains the optional instance parameter. However, it does not explicitly mention when not to use it or directly reference sibling tools as alternatives, but the context 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?

No annotations are provided, so the description must fully convey behavioral traits. It discloses that the link is signed and short-lived (~30s) and that the tool only works for already-processed local files. It does not mention whether the tool has side effects or requires authentication, but the operation is a read (download link generation), which is consistent with the description. Additional details on error handling or preconditions would improve transparency.

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 relatively concise, containing only necessary facts across two languages (English and Persian). It is front-loaded with the main purpose. The bilingual content is somewhat redundant for an English-speaking AI agent, but not excessive. Every sentence adds value, though the Persian version could be omitted without loss of clarity.

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 lack of annotations and a simple output schema, the description covers key aspects: endpoint, return value, link expiry, and file state requirement. However, it omits potential error conditions (e.g., what happens if the file is not processed or the document URL is invalid) and does not clarify if there are rate limits or cost implications. While adequate for basic use, it leaves gaps for robust agent handling.

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 must clarify all parameters. It only addresses the instance parameter (optional, defaults to default instance). The required document_url parameter is not explicitly described; its purpose is only implied by the tool's overall function. The agent would need to infer that document_url identifies the document, but format or constraints are missing. This gap lowers the score.

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 gets a signed link to download the original source file, specifying the endpoint (POST /api/download_original/) and return value ({download_link}). It distinguishes from sibling tools like alefba_download_pdf by emphasizing 'original' file, ensuring the agent selects the correct tool for the intended file type.

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 the tool works only for already-processed local files and that the instance parameter is optional, defaulting to the default instance. It implicitly differentiates from siblings (alefba_download_excel, etc.) by focusing on original source, but does not explicitly list when to use alternatives. Nonetheless, the guidance is sufficient for correct tool selection.

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?

Explains parameter effects (quality, color, img_format) and return behavior (download info vs. saved path). Lacks details on whether the operation is synchronous, modifies state, or requires prior analysis.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is front-loaded with English purpose but includes redundant Persian translation. Could be more concise without losing clarity.

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?

Adequate for a 6-param tool with output schema; explains all parameters except document_url. Missing contextual info like document must exist and be analyzed, and any limitations or prerequisites.

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 has 0% description coverage, so description compensates by explaining quality (0-100), color (color vs grayscale), img_format (png|jpg), save_path, and instance. Adds meaning beyond schema names.

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 the analyzed document as a searchable PDF, with a distinct verb and resource. It differentiates from sibling tools like download_excel and download_original.

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 guidance on when to use this tool versus alternatives (e.g., download_original, download_word). Missing prerequisites like document must be analyzed first.

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?

With no annotations, the description carries full burden. It discloses the HTTP method (POST), the API endpoint, the conditional behavior of save_path (local save), and the requirement that the document be processed. It does not mention idempotency or side effects, but for a download tool the behavioral disclosure is fairly complete.

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 and front-loaded. It consists of clear sentences covering purpose, API call, return behavior, prerequisite, and optional parameter. No unnecessary words or repetition. The bilingual addition (Persian) does not hurt conciseness as it's a repetition.

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 complexity (3 params, 1 required, no enums, output schema present), the description covers the key aspects: prerequisite (processed), behavior for save_path, and instance targeting. It leaves out possible error conditions or permission details, but for a download tool this is sufficient. The presence of output schema reduces the need to describe return values.

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%, so the description must compensate. It explains each parameter: document_url (implicitly the document to download), save_path (if provided saves locally), and instance (optional instance name). This adds meaningful context beyond the schema, though it could be more explicit about the format/source of document_url.

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 a document as Word (.docx) file, which is a specific verb and resource. It distinguishes from sibling download tools like alefba_download_excel or alefba_download_pdf by specifying the format. The purpose 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 mentions a prerequisite (document must be processed) and the optional instance parameter. However, it does not explicitly compare this tool to other download alternatives (e.g., when to use alefba_download_word vs alefba_download_pdf). The guidance is adequate but lacks explicit when-not-to-use or alternative referral.

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?

No annotations are provided, so the description carries full burden. It discloses the async polling behavior: returns {state} if running, full result when done; wait=true blocks server-side. However, it does not mention error cases like invalid task_id or authentication needs, limiting transparency.

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 with no extraneous sentences. It front-loads the main purpose and includes bilingual text. Minor improvement could be more structured bullet points, but it remains clear and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, output schema exists), the description covers the core usage. It explains the async result retrieval and blocking option. Not fully comprehensive about possible states or output schema details, but sufficient for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates fully by explaining each parameter: task_id (from async read), wait (optional, default false, for blocking), instance (optional, defaults to default). This adds essential meaning beyond the JSON 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 'Fetch or poll the result of an async document read', specifying the verb 'fetch/poll' and the resource 'result of an async document read'. It distinguishes from siblings like alefba_read_document by explicitly linking to its async invocation.

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 when to use the tool: 'Pass a task_id returned by alefba_read_document(wait=false)'. It provides usage context by describing the polling behavior and the option to block with wait=true. No explicit alternatives or when-not-to-use, but the guidance is clear.

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?

With no annotations, the description carries the burden of transparency. It discloses the HTTP method (GET), the API endpoint, the response structure, and pagination behavior. It does not mention authentication or error conditions, but the read-only nature is implied by 'List'.

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 fairly concise, including both English and Persian. It front-loads the core action and explains pagination and parameters efficiently. Every sentence adds useful information, though the Persian could be separate.

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 output schema exists and annotations are absent, the description covers essential aspects: pagination, default values, optional instance, and response fields. Missing error handling or rate limits, but adequate for a listing 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 0%, so the description adds value by explaining the 'page' parameter (default 1, pagination) and 'instance' parameter (optional instance name, default instance). This compensates for the lack of schema descriptions, though the valid values for 'instance' are not specified.

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 lists documents page by page from an Alefba instance. It specifies the verb 'List' and the resource 'documents', and distinguishes from sibling tools like alefba_detail_document by focusing on pagination and listing.

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 pagination using num_pages and defaults, but does not provide explicit guidance on when to use this tool versus alternatives like alefba_detail_document or when to specify different instances. Usage context is implied but not fully explicit.

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?

With no annotations, the description details synchronous blocking behavior, returned structure, async queuing, and polling. It does not mention rate limits or authorization but discloses core behavior sufficiently for a read operation.

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 and includes both languages, which adds length but is necessary. It efficiently covers key behaviors in a structured manner, though could be slightly more concise.

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 8 parameters, output schema, and sibling tools, the description covers sync/async modes, output structure, parameter roles, and instance targeting. Missing details on fix_orientation and word_positions, but overall complete for safe usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description explains document_url, type, wait, priority, task_id, and instance. Missing descriptions for fix_orientation and word_positions. This adds significant meaning beyond the schema for most parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: OCR from a URL, with both English and Persian text. It distinguishes from siblings like alefba_read_document_callback and alefba_read_document_upload by mentioning polling with alefba_get_result for async mode.

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 synchronous default behavior, async option with polling, and key parameters (type, priority, task_id, instance). It implies when to use sync vs async but does not explicitly exclude alternatives like alefba_read_document_upload for uploads.

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?

No annotations are provided, so the description carries the full burden. It discloses the immediate return of {state:'processing', document_url} and the async callback mechanism. However, it does not explain error handling, retry behavior, or authorization needs, leaving some behavioral gaps.

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 long, including a Persian translation, and front-loads the key purpose. It is concise without being terse, though the bilingual text adds some length. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no annotations, and an output schema (though not shown), the description explains the basic workflow and response shape. It does not cover failure scenarios, callback guarantees, or integration with sibling tools like alefba_read_document. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description adds meaning for all three parameters: document_url (the document to read), callback_url (where to POST result), and instance (target instance, defaults to default). This compensates well for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads a document and returns results via webhook callback, distinguishing it from synchronous polling tools like alefba_read_document. The Persian translation 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 explicitly positions this tool as an alternative to polling, stating that Alefba will POST the result to callback_url. It mentions the optional instance parameter, providing clear context for when to use 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?

Discloses multipart upload, return format variation with wait parameter, and instance targeting. No annotations provided, so description compensates well. Could mention potential side effects or delays, but overall transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise: four sentences covering action, technical detail, return behavior, and optional parameter. Front-loaded with core purpose. Farsi translation is possibly redundant but not detrimental.

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 output schema exists, description explains return alternatives. Lacks explicit differentiation from sibling tools and constraints like file size/types. But for a typical OCR tool, reasonably complete.

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 has 0% description coverage. Description adds meaning for file_path (implied), wait (return format), and instance (target). For other parameters (type, fix_orientation, word_positions, priority), it only references sibling tool without details, which is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it uploads a local file for OCR reading. Distinguishes from sibling alefba_read_document by specifying local file upload and multipart form data. The bilingual text adds no confusion.

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?

Implicitly indicates use for local files vs. other methods (alefba_read_document likely for URLs). Mentions same options as sibling, hinting at alternative. No explicit exclusions, but context is clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format (structured result or async) and the required format for page URLs, but does not explicitly state that the operation is read-only, non-destructive, or mention any permissions. The behavioral traits are implied but not fully transparent.

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: two English sentences and one Persian sentence, front-loading the purpose. It includes a usage example. The bilingual aspect is slightly redundant but does not detract. Overall, it is efficient and well-structured.

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 has 7 parameters, no annotations, and an output schema (not detailed), the description explains the core input and return type but fails to cover most parameters. It provides enough context for a niche tool but is incomplete regarding optional parameters and output specifics.

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 only adds meaning for page_urls (URL format with @page=N) and instance (optional, default). The other five parameters (type, fix_orientation, word_positions, wait, priority) are not explained, leaving significant gaps. The description does not compensate adequately for the missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read (OCR) specific pages of documents.' It explains the page URL format with @page=N suffix and specifies the return type (like alefba_read_document or async). This distinguishes it from the sibling tool alefba_read_document, which reads full 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?

The description mentions that it returns the same structured result as alefba_read_document, implying similarity, but it does not explicitly state when to use this tool versus alefba_read_document or other siblings. No direct when-not or alternative guidance is provided beyond this indirect reference.

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?

Discloses the HTTP GET call and return value, but does not mention authorization or safety implications. However, it is a read-only healthcheck with no side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise two-sentence description with bilingual support, front-loading the English purpose and providing all necessary information 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?

Covers return format with example, parameter usage, and endpoint details. The presence of an output schema complements the description, making it fully informative.

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 description fully explains the optional 'instance' parameter, including its purpose and default behavior, adding value beyond the bare schema which lacks descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if an Alefba instance is up and ready, specifies the HTTP endpoint and return format, and distinguishes itself from sibling document management 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?

Describes the optional 'instance' parameter and default behavior, but lacks explicit guidance on when not to use or alternatives, though the context of siblings makes this clear.

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?

With no annotations provided, the description carries full burden. It discloses the return format including fields like 'default_instance', 'name', 'base_url', and 'verify_ssl', and explicitly states that tokens are never returned, adding important behavioral 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 concise with two English sentences and a Persian repetition that could be omitted, but it is front-loaded with the core purpose. It wastes no 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?

Given the tool's simplicity (no parameters, output schema present), the description is complete. It explains what is returned, the benefit of using the tool, and a behavioral caveat about tokens, leaving no gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters and schema description coverage is 100%, so no parameter documentation is needed. The description adds value beyond the schema by explaining the return structure and the purpose of the tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list', the resource 'instances', and the scope 'names and base URLs only'. It also explains the utility for discovering instance values for other tools, distinguishing it from sibling tools that perform document operations.

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 mentions that this tool is useful for discovering which 'instance' values other tools accept, providing clear when-to-use guidance. However, it does not mention any alternatives or when not to use it.

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?

No annotations provided, so description carries full burden. The description indicates a read-only documentation retrieval behavior, but does not explicitly state side-effect-free nature or any behavioral traits. However, for a documentation tool, this is sufficiently transparent.

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 (including a Persian translation) and front-loaded with the core purpose. The Persian translation adds redundancy for English-only users, but remains appropriately sized for its bilingual context.

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 role as a documentation meta-tool with one optional parameter and an output schema, the description fully covers what it returns, when to use it, and how to filter. It also links to official docs, making it complete for its purpose.

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 parameter 'topic' has 0% schema description coverage, but the description adds meaning by stating it is optional and used to filter to one tool or doc link. This compensates for the missing schema description, though possible values or format are not specified.

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 returns documentation about Alefba OCR and the MCP tools themselves, with a specific verb 'Return documentation'. It distinguishes from sibling tools, which are document operation tools, by highlighting its role as a documentation/guidance tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use this to learn what the server does, which tools exist, and where to read the official docs before calling other tools.' This provides clear usage context and implies not using it for direct operations.

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