search_healthcare

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

With no annotations, the description carries full burden. It discloses that the tool is free with no key, searches multiple specific sources, returns title, identifiers, provenance URL, and record_id, and that full records require payment. It does not mention rate limits, result limits, or error conditions, but provides substantial behavioral context beyond what annotations would typically offer.

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 information-dense and logically organized, covering availability, sources, return fields, payment model, use cases, and alternatives. It is slightly longer than necessary with minor redundancy ('Free to search' repeats the opening) but every major aspect 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?

For a single-parameter search tool with no output schema, the description adequately explains what is searched, what is returned, and how the free vs paid model works. It does not specify pagination, sorting, or result count limits, but these are not critical for basic usage and the description otherwise feels 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 schema has only a 'query' field with no description, but the tool description's Args section explains 'query: keyword(s) to search, e.g. a provider name or NPI, drug name, condition, or NCT id.' This fully compensates for the schema's lack of parameter documentation.

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 explicitly states it searches healthcare registries including CMS NPPES, RxNorm, ClinicalTrials.gov, and FDA recalls, and returns matching records. It distinguishes itself from sibling lookup_entity and get_record by clarifying the search use case and the paywall for full records.

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?

It clearly states suitable use cases: 'For provider verification, prescriber vetting, trial status checks, and drug safety review.' It also directs to alternatives: 'To verify a provider by identifier rather than search for one, call lookup_entity' and 'call get_record with a record_id to buy the full record.' This explicitly covers when to use this tool versus siblings.

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