eth_search_resources

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

The description adds substantial behavioral guidance beyond the annotations: it explains that an empty result is a meaningful statement about the catalog, instructs the agent to follow the `hint` field before reporting absence, and forbids guessing in place of missing results. This is valuable context not present in the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint annotations. No contradiction with annotations exists.

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: the primary purpose is front-loaded, followed by API context and search capabilities, and the FID-003 behavioral rule is clearly separated. Every sentence carries operational value, and the section about empty results earns its place because it dictates agent behavior. No filler or redundancy is present.

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 complex search tool with no output schema, the description covers the endpoint, supported search features, and the crucial empty-result/hint protocol. It is somewhat lacking in explicit return-format details and sibling differentiation, but the referenced `hint` field and API endpoint give an agent enough orientation to proceed confidently.

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 0%, and the description does not compensate by explaining the parameters. It mentions supported search modes and pagination at a high level, but provides no detail on the query format, sort options, filters, or defaults. The nested schema contains rich parameter descriptions, but the tool description itself adds little semantic value for parameter understanding.

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: 'Durchsucht den Katalog der ETH-Bibliothek mit über 30 Millionen Ressourcen.' It clearly identifies the tool as a catalog search operation and distinguishes it from siblings such as eth_search_archive or eth_get_resource by focusing on the general 30M-resource catalog. The mention of free-text, field search, facets, and pagination further clarifies its 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?

The description gives clear context that this tool is for searching the ETH library catalog and names supported capabilities, so an agent can infer when to use it. However, it never explicitly contrasts it with alternatives like eth_get_resource or eth_search_by_type, nor does it state when NOT to use this tool. Usage is implied rather than directly guided.

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