fda_substance

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

The readOnlyHint annotation already signals a safe read operation; the description adds specific query syntax for this dataset (e.g., names.name, unii, structure.formula), which guides the agent beyond generic schema descriptions. No side effects or hidden behaviors are disclosed, but none are needed for a read-only search.

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 compact and front-loaded with the purpose, followed by four concrete examples. Every line adds value, and the format is 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?

For a read-only search tool with two parameters and no output schema, the description adequately covers what the tool does and how to query it. It lacks explicit info about response structure, but for a search tool, the search syntax and purpose are the critical parts; the schema handles parameter details.

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?

With 100% schema coverage, the baseline is 3; the description enhances the search parameter by showing domain-specific field syntax (CAS, UNII, molecular formula) beyond the generic OpenFDA query examples in the schema. The limit parameter is already fully documented 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 explicitly states the tool 'Search FDA substance data' and specifies searchable identifiers (name, CAS code, UNII, molecular formula), clearly distinguishing it from sibling FDA tools for events, labels, and NDCs. The example queries reinforce the specific resource and search scope.

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?

Provides clear context that this tool is for substance-level ingredient lookups and shows example queries for different identifier types. However, it doesn't explicitly exclude other FDA tools or mention alternatives when a different dataset is needed.

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