img2text

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

With no annotations provided, the description carries the full disclosure burden and substantially meets it: it reveals the external vision-model dependency (VISION_PROVIDERS OpenAI-compatible models with automatic fallback), the plain-text return type, and its purpose for non-multimodal models. It also prescribes output style behavior (one-sentence summary, then key details, no lengthy analysis). It does not cover error behavior or latency, but the fallback mechanism and non-mutating nature are clearly conveyed.

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

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

Dense but well-structured: purpose, input formats, mechanism, numbered usage conditions (①②③), prompt guidance, and output-style instructions each get focused coverage with no fluff. The numbered lists make the routing logic easily scannable. Minor redundancy with schema text (image formats and max_tokens restated) keeps it just short of a 5.

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 3-parameter tool with no annotations, no siblings, and no output schema, the description covers everything needed to invoke it correctly: accepted input formats, when to call, what the prompt parameter should contain, and how to relay the result. The only omitted aspect is explicit error handling, which the automatic-fallback note partially addresses.

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 genuine value for 'prompt' by specifying exactly when to pass the user question versus omitting it to use the server default. The 'image' parameter gains an operational hint that '图片文件：' in attachment references marks the absolute path. 'max_tokens' adds nothing beyond the schema, but overall the description exceeds the baseline.

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 a specific verb-object pair ('读取图片并把内容转换为文字描述' — read an image and convert to text description), enumerates accepted input formats (local path, http(s) URL, data URL, base64), and clarifies the tool exists for models that lack native image input. It also differentiates from native multimodal viewing ('你能直接查看图片时...无需调用本工具'), so an agent can distinguish this path from alternatives.

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?

Three numbered conditions give explicit when-to-call guidance: call immediately when a user supplies an image path/URL/attachment reference the model cannot see (explicitly instructing not to reply '无法查看图片'), skip the tool when the model can already view the image, and call when the user asks for image analysis. The prompt parameter also receives explicit passing rules ('用户有具体问题时传用户的问题；没有问题时不要传'). This is exemplary usage routing with exclusions and alternatives.

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