search_wlo_topic_pages

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses specific output behaviors: result titling falls back to the owning collection or cm:title, never a cryptic ID; multiple variants are merged; target groups are returned as readable labels; ordering is deterministic. These details go well beyond basic search behavior and fully inform the agent of what to expect.

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 lengthy but well-structured with clear sections for search modes, output behavior, and ordering. Each sentence contributes useful information without redundancy. It could be tightened slightly, but given the complexity of the tool, the length is appropriate and easily digestible.

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?

Despite having no output schema, the description fully covers what the agent needs to know: the three modes, how results are titled and merged, target group label behavior, and deterministic ordering. All 8 parameters are semantically addressed in either the schema or description, and the tool's behavior is explained comprehensively. No significant gaps remain.

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 high (88%), so the baseline is 3, but the description adds real semantic value. It explains the meaning of query ('searches collections first, then checks linked Themenseiten'), collectionId ('bypasses the search'), and the sort parameter's behavior. It also clarifies output-related nuances like variant merging, which indirectly enriches understanding of mergeVariants and targetGroup. This extra context justifies a 4.

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 states the tool searches for Themenseiten (topic pages) on WirLernenOnline, using a specific verb and resource. It further distinguishes itself from siblings by detailing three distinct search modes (by collectionId, by topic, by filters only) and emphasizing the link to collections, making it unambiguous when this tool is appropriate.

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 clear context for each mode: collectionId is for a direct check, query is for thematic search, and filters-only lists all. The collectionId parameter explicitly mentions bypassing the search and being useful when a collection is already known from search_wlo_collections. However, it does not explicitly compare against all sibling tools (e.g., search_wlo_content, get_topic_page_content) to state when to prefer this one, so a small gap remains.

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