Get ready for my doctor's appointment (no lab values or records needed)

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

Annotations already declare it read-only, idempotent and closed-world, and the description still adds real substance: cost ('Free'), retention ('Nothing is stored'), a stable job_ref retrievable later via get_job_result, and a guaranteed trailing next_steps block. The only soft spot is that 'Nothing is stored' sits in mild tension with a job_ref that reproduces the sheet later in a new conversation.

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?

Front-loaded with the trigger condition and the payoff, then the input burden, then the job_ref lifecycle, then the disclaimer. It is long and the clinician list in prose duplicates the visit_with enum, but nearly every clause carries genuine signal.

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 a five-parameter tool with a nested status object and an output schema, the description covers the trigger, the inputs required and explicitly not required, the shape of the return, the follow-up retrieval path, cost, retention, and the non-diagnostic framing. Nothing an agent needs in order to call it or to decide to call it is missing.

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 100%, so the baseline is 3; the description earns above that by telling the agent the call is deliberately low-burden, using only condition, a few medicine classes, which clinician, and per-test status as recent/overdue/never/unsure. It adds intent and framing rather than syntax, which is the right thing to add here.

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?

States a specific verb and resource ('be ready' for an 'upcoming appointment') plus the exact contents of the reply (checks, questions, what to bring, printable visit sheet). The parenthetical 'no lab values or records needed' carves it away from sibling record/lab tools such as get_my_medical_records and explain_my_lab_results.

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?

Gives a clear triggering condition (a person with an upcoming appointment for one of the listed conditions who wants to be ready) and an explicit negative requirement (no labs, dates, names, or records). It also routes to get_job_result for later retrieval, but never names or contrasts siblings like check_care_gaps, so when this beats the care-gap tool is left to inference.

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