patient_ad_note

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

No annotations are provided, so the description carries the burden. It adds useful context: the return format is HTML, and the API requires YYYYMMDD format but the tool automatically converts from YYYY-MM-DD. Nevertheless, it does not mention authentication requirements beyond the schema parameters, error behaviors, or what happens if no record is found.

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 well-structured: a one-line purpose, an Args section, a detailed example, and a brief note about internal conversion. It is not overly verbose and the example is genuinely useful for executing the tool correctly. It slightly exceeds the minimal needed but each section earns its place.

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 no output schema and no annotations, the description covers the essential usage: what the tool does, how to obtain required inputs, and the date format conversion. It is adequate for a note-retrieval tool, though it could benefit from stating the output structure or any error scenarios. Overall it is complete enough for an agent to invoke correctly.

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 coverage is 0%, so the description must compensate. It explains caseno as the admission case number from patient_ad_list and adidate as the admission date with format flexibility and conversion. However, it does not describe eip_id, eip_password, and hisno, which are likely common across siblings but still undocumented in the 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 clearly states the tool's purpose: '取得住院病歷摘要 (HTML)' which means get inpatient admission note summary in HTML format. It identifies the specific resource (住院病歷摘要 / admission note) and distinguishes it from sibling tools like patient_opd_note and patient_consult_note which handle different clinical document types.

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 a clear step-by-step example showing that the tool should be used after patient_ad_list, and it explains exactly how to obtain and pass the required caseno and adidate from that prior call. However, it does not explicitly state when to avoid using this tool or mention alternative tools.

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