start_pdf_ocr

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

没有任何 annotations，描述承担了全部行为披露义务。它清楚说明了异步后台执行、立即返回、可查询的进度字段、完成后的 result 字段内容，以及可取消。这些信息远超基本操作定义，能帮助 agent 正确预期副作用和后续流程。

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?

描述紧凑但信息密度高，第一句就给出核心行为和返回值，第二段补充了进度查询、结果形态和取消方式。没有冗余内容，结构也便于 agent 快速解析。

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?

异步任务的生命周期（启动、查询、取消、结果获取）描述得比较完整，且与兄弟工具衔接明确。但 pages 参数格式完全未说明，且没有输出 schema，导致 agent 在参数构造和返回值细节上仍存在明显缺口。

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

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

Schema description coverage 为 0%，描述完全没有补偿参数语义。path 和 pages 两个参数均未说明格式、取值范围或示例，尤其是 pages 的可选值（如页码范围写法）完全缺失，agent 无法仅凭描述正确构造参数。

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?

描述明确指出“异步启动 PDF OCR 并立即返回 task_id”，动词和资源清晰，且与同步 OCR 或图片 OCR 等兄弟工具在用途上有了明确区分。开头的“异步”和“超大 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?

描述说明了适用场景（超大 PDF，避免长时间阻塞），并明确指引使用 get_ocr_status 查询进度、用 cancel_ocr_task 取消任务。虽然没有显式说明何时不应使用本工具，但已提供了清晰的上下文和操作路径。

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