alefba_read_document

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.