Search FDA medical device clearances (510(k), PMA)

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the baseline is covered. The description adds genuinely useful behavior beyond that: it names the backing Apify Actor, discloses per-decision cost (~$0.004) and a $0.5 per-call spend cap, and notes that cost scales with max_items — material facts for an agent deciding whether to call it or how to size the request.

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?

Three sentences, front-loaded with the resource and scope before filtering and cost details. The opening field enumeration is long but each item informs what a caller can retrieve; little is wasted, though the list could be tightened.

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?

An output schema exists, so return values need not be described, and the schema plus description together cover filters, cost, and execution model. The main residual gap is that the description doesn't warn that results default to only the last 30 days of decisions, which an agent could easily miss when interpreting an empty or narrow result set.

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 100%, so every one of the 9 parameters is already documented with examples and constraints. The description's filter summary ('date, company, device words, product code, specialty and class') merely restates the schema and does not flag the consequential default of decided_within_days=30, which silently narrows results.

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 opens with a specific verb and resource ('FDA medical device 510(k) clearances and PMA approvals') and enumerates exactly what data is returned (applicant, product code, panel, class, review days, decision, links). This is unmistakably distinct from siblings like search_clinical_trials or search_recalls, which cover different regulatory datasets.

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 states a clear usage context ('medtech competitive intelligence and sales prospecting') and lists the available filter axes, so an agent knows what this tool is for. It stops short of explicit when-not guidance or naming an alternative sibling (e.g. clinical trials vs. clearances) for overlapping research questions.

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