bakom_aktuell

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: sorting by metadata_modified descending, no news fetching (with reason), full-text search limitations (no topic facet, unknown topics return empty list with hint), and the implication that results are date-ordered not relevance-ordered. This goes well beyond the annotation hints.

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 efficiently structured: a clear one-sentence purpose, followed by important caveats in bullet points. Every sentence adds value (e.g., sorting behavior, no news, search limitations, relevance warning). It is front-loaded with the main purpose and uses appropriate German terminology without fluff.

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 the tool's simplicity (1 parameter with nested sub-params) and the presence of annotations and an explicit output schema, the description covers the key behavioral aspects: data source, sorting, search behavior, empty results handling, and the exclusion of news. It does not explain the output schema structure in words (but the embedded Schema block suffices). Minor gap: no mention of the openWorldHint annotation's implications, but overall quite complete.

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% for the top-level 'params' parameter, though nested fields have rich descriptions. The description adds meaningful context for 'thema' (explaining it's a full-text search without topic facet, and that unknown topics return empty results). It does not describe 'response_format' beyond what the schema already provides. Overall, the description partially compensates for the top-level coverage gap.

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 'Zuletzt aktualisierte BAKOM-Datensätze auf opendata.swiss zu einem Thema', providing a specific verb (abfragen von aktualisierten Datensätzen) and resource (BAKOM-Datensätze auf opendata.swiss). It distinguishes itself from sibling tools like bakom_broadband_coverage or bakom_medien_statistik by focusing on recently updated datasets across any topic, not a specific domain.

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 explains when to use this tool (to see what BAKOM recently worked on) and explicitly states what not to expect: 'Keine Medienmitteilungen.' It warns about the sorting by date reducing relevance ('ein Treffer kann das Suchwort nur am Rand berühren') and advises where to find news instead. However, it does not directly compare with sibling tools or specify conditions that would make this tool preferable over others.

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