AI-Process Health Card

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 asynchronous HTTP flow ('202 + Location poll'), the output file ('saves process_health_card.json'), and the required IsAsync=true flag. It also explains doc_name extension fallback behavior. This goes well beyond a minimal description, though it omits error behavior and auth requirements.

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 a single dense paragraph with no redundant filler; every sentence adds technical value. It front-loads the core purpose. Minor redundancy appears in 'no customFieldKeys or CustomFieldKeys' (likely a case-variant typo), slightly reducing polish.

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?

The description covers the main invocation path, async behavior, and output file, which are essential for a tool with no output schema. However, it leaves output_dir unexplained, does not describe the structure of the extracted data, and lacks guidance on error handling or prerequisites. For a simple 3-param tool, this is adequate but not fully 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 description coverage is 0%, so description must compensate. It explains pdf_file_path (local .pdf/.png/.jpg/.jpeg as Base64) and doc_name (optional, defaults to basename, .jpeg fallback). However, output_dir is completely undocumented in both schema and description, leaving a significant gap.

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 verb and resource: 'extract structured data from a health card image/PDF'. It specifically names the document type (health card), distinguishing it from other process_* siblings. The mention of the PDF4me endpoint adds specificity.

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 the tool is for health cards through its title and first sentence, and it gives operational constraints (only docContent/docName/IsAsync, no customFieldKeys). However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or alternative tools for non-health-card documents.

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