careflow_government_forms

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

There are no annotations, so the description carries full burden. It discloses mandatory human review, input format restrictions (e.g., 'HEIC/HEIF only when discovery reports support'), and the need to continue the same job via status/review/export. This is substantial, though it could add detail about error behavior or permission 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 consists of three dense sentences with no wasted words. It front-loads the core purpose, then gives prerequisites and exclusions, and ends with the required workflow. Every sentence contributes unique value and is easily scannable.

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 the tool's complexity (multi-step job with template selection, source handling, review, and export) and minimal annotations/schema, the description covers the essential workflow and constraints. The existence of an output schema likely covers return value details, so the description is well-rounded, though 'request_id' remains unexplained.

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 schema provides 0% description coverage, but the text effectively explains key inputs: 'template_id', 'one source' (text, image path, elder_profile object), and the operation lifecycle (status, review, export). It does not explicitly enumerate `operation` string values, but the workflow strongly implies them, offering meaningful help beyond the bare schema.

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 states a specific action and resource: 'Fill a bundled Hong Kong government welfare-form PDF from elder information.' It also includes a distinctive qualifier ('mandatory human review before export') and clearly differentiates from sibling tools by focusing on PDF generation from elder data rather than Excel conversion or meeting notes.

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 provides explicit usage directions: 'Call list_templates first or start with a template_id and exactly one source.' It also lists disallowed input types ('does not accept a blank government PDF, completed volunteer visit forms, audio, Word, or Excel files') and outlines a clear multi-step workflow ('Continue the same job with status, review using every preview field, then export').

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