Find Series

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

With no annotations, the description carries full disclosure burden. It reveals the critical limitation that only ~20 curated series are searched, that empty results mean 'not curated yet' rather than nonexistence, and mentions the no_match_hint field. This prevents the agent from drawing false negative conclusions—an important behavioral trait not otherwise visible.

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 front-loaded with the core purpose and immediately follows with the key usage rule. Every sentence earns its place: the corpus limitation, the no_match_hint reference, and the raw_query_url fallback all add necessary operational context. No redundant filler.

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 single parameter, an output schema that covers return values, and the description's coverage of edge cases, nothing essential is missing. It addresses how to handle empty results, where to find broader data, and when to use the tool relative to siblings.

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 0% and the only parameter is a bare 'query' string. The description supplies meaning by clarifying the query should be a natural-language question about Malaysian official statistics. This is sufficient contextual definition for the single parameter to be used correctly.

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: 'Find candidate series for a natural-language question about Malaysian official statistics.' It explicitly distinguishes itself from get_series by saying to always call this first if no series id exists. The behavior and scope are unambiguous.

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 explicit when-to-use guidance: 'always call this before get_series if you don't already have a series id.' It also explains how to interpret empty results and directs the agent to raw_query_url after locating the dataset via other means. This fully covers selection and fallback behavior.

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