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

Beyond the readOnlyHint and openWorldHint annotations, the description reveals ordering behavior ('ordered by popularity'), the exact return shape, the relationship between returned IDs and get_fred_series, and the API-key failure mode. This gives the agent a realistic model of what the tool will do and return.

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 with clear sections: summary, Args, Returns, Examples, and Errors. Every sentence adds useful information, and the most important usage guidance is front-loaded. Despite its length, it remains focused and 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?

The description covers what the tool does, how to invoke it, what the response looks like, how to use the response with a sibling tool, and the primary error condition. An agent has everything it needs to decide when to call this tool and what to do with the result.

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 input schema already covers both parameters at 100%, so the baseline is 3. The description adds value with richer query examples ('unemployment rate korea', 'housing starts'), explains that results are ordered by popularity, and clarifies how the query maps to real-world series IDs. This goes beyond simple schema repetition.

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 identifies the tool's verb ('Search'), resource ('FRED catalog for economic time series'), and key qualifier ('by keyword, ordered by popularity'). It also distinguishes itself from get_fred_series by explaining that returned IDs should be passed to get_fred_series, so an agent can tell these siblings apart.

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 explicit when-to-use context: keyword-based discovery when the series ID is unknown. It also gives a direct when-not-to-use rule: if you already know the series ID, call get_fred_series instead. This is exactly the kind of guidance needed to route an agent correctly.

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