extract_text

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

With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals that the tool returns a 'single JSON response' and imposes a security constraint ('must be under home directory'). However, it does not mention error handling, supported file types, or explicitly state that it is a read-only operation, leaving some behavioral aspects undisclosed.

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 short and front-loaded with the primary purpose. It uses three concise sentences with no unnecessary fluff, and the Args section clearly explains the parameter 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?

For a one-parameter tool with an output schema, the description covers the essential invocation details: what it does, the path requirement, and the combined output. It does not specify image format limitations or failure modes, but these are not critical for a basic extraction tool. Overall, it is adequately 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?

The input schema provides no description for the single parameter (coverage 0%), so the description fully compensates by explaining that image_path must be an absolute path under the home directory. This adds crucial semantic meaning beyond the schema's bare string type.

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 'Extract all text and metadata from an image' with a specific verb and resource. It also distinguishes itself from siblings by calling itself a 'convenience wrapper' that combines OCR text extraction with image metadata, making it distinct from the standalone ocr_image and image_metadata 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?

The description implies usage context by labeling the tool a 'convenience wrapper' that combines OCR and metadata into one response, suggesting it should be used when both are needed. However, it does not explicitly state when not to use it or directly reference the sibling alternatives, so it stops short of full guidance.

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