Adios: Croatian news

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description goes beyond them by disclosing what the payload contains for each id type — summary, context, cross-portal duplicates, location, or full story timeline. It does not mention rate limits or auth requirements, but that is minor for a read tool.

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?

A single sentence that front-loads the core action and then lists return contents economically. The parenthetical prefix forms and the colon-list are dense but readable; nothing is wasted.

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?

With an output schema present, the description is not obligated to explain return values yet it still characterizes them usefully. Combined with annotation and schema coverage, an agent has enough to invoke this correctly; the only gap is the missing routing rule versus get_article and get_story_timeline.

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 already 100% with a single documented 'id' param, so baseline is 3. The description adds real value beyond 'An id from search' by specifying the required 'article:…' or 'story:…' prefix formats, which is information the schema does not carry.

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 ('Fetch one result of search by its id') and enumerates what the prefixes return (article summary/context/other portals/location, or a story timeline). This clearly separates an article-prefixed id from a story-prefixed id. It stops short of naming the closely related siblings get_article and get_story_timeline, so an agent still has to infer which one to prefer.

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 phrase 'one result of search by its id' implies the tool is used downstream of search, which is the key context. However, there is no explicit when/when-not and no routing guidance against get_article or get_story_timeline, which appear to cover overlapping ground.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds substantive context by disclosing exactly what depth of data is retrieved—neutral summary, background, cross-portal coverage, timeline, and badges—which goes beyond the annotations.

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?

Front-loaded with the core purpose, then a dense but purposeful enumeration of return facets and a routing sentence. The list of returned items is long, but each item is informative rather than 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?

For a read-only single-resource lookup with full schema coverage, an output schema, and clear annotations, the description covers what an agent needs: what it returns, its id input, and where it fits in the toolchain. No meaningful 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 100% and the single 'id' parameter is documented there as coming 'from a list or a search.' The description's phrase 'by id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 ('Full details of one news article by id') and enumerates the returned facets (summary, topics/entities, other portals, related articles, map location, timeline, signals/badges). It clearly distinguishes this single-article enrichment tool from the list/search siblings it names.

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?

Explicitly says to use it 'after get_latest_news, search_news or get_nearby_news to explain a story,' which names concrete upstream tools and the intent. It lacks an explicit when-not-to-use (e.g. don't use for browsing) but the routing context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: a 30-day window, newest-first ordering, and returned place/distance fields.

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 time window, geography, ordering, and return-field details. The long city parenthetical is justified by demonstrating coverage, and the final instruction is short and useful.

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?

With rich annotations, an output schema, and full schema description coverage, the description supplies the important context an agent needs: Croatian-city scope, 30-day window, newest-first ordering, and result fields. It is only slightly incomplete in not routing against nearby/latest/search alternatives.

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 100%, so the schema already documents all four parameters, including the kinds enum and filler behavior. The description adds city examples and the name-or-slug instruction, but much of that repeats the schema and it does not deepen semantics for kinds, limit, or include_filler.

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 states a specific resource and scope: last 30 days of Croatian city news, newest first, with place and distance from the city centre. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as get_nearby_news or get_latest_news.

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 scope implies when to use it for a specific Croatian city, but there is no explicit when/when-not guidance and no named alternative such as get_nearby_news, get_latest_news, or search_news. The instruction 'Pass the city name or slug' is a parameter hint rather than usage routing.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, but the description adds real freshness context ("Today's is updated live during the day") and explains that croatia_only removes the world section and its stories. That is useful behavioral detail beyond the structured 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?

Purpose and content are front-loaded before the filtering rule and use cases, with no filler. The long parenthetical section list is slightly dense but pays for itself by describing the digest's structure.

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?

With an output schema present, the description needn't explain return values, yet it still outlines the digest structure, freshness, the croatia_only effect, and appropriate use cases. Nothing an agent needs to call this correctly is missing.

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 100%, so both parameters are already documented, and the description's "croatia_only=true leaves out the world section and its stories" largely restates the schema's own wording. Baseline 3 applies when the schema carries the parameter semantics.

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 artifact (Adios's written daily summary, "Pregled dana") and enumerates its contents: sections, day timeline, and linked stories. An agent can distinguish it from siblings like get_weekly_digest or get_latest_news purely from this text.

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?

Explicitly says when to use it: "what happened today/yesterday," morning briefings, and recaps. It does not name an alternative for narrower needs (e.g., a single story via get_article), so it stops short of the when-not/alternative level.

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

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

Annotations already establish the safe read-only/idempotent profile, so the description only needs to add context, and it does: deduplication semantics, filler exclusion by default, archive scoping ('within the plan's archive'), and plan-capped result limits. These are genuine behavioral traits an agent couldn't infer from the annotations, though pagination/output behavior is not elaborated.

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?

Purpose and filters are front-loaded, but the second sentence is a dense run-on that enumerates return fields ('title, description, Adios URL, source portal...') already defined by the output schema, adding length without new decision-relevant information.

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 10-parameter read tool with full schema coverage, output schema, and rich annotations, the description covers filtering intent, default exclusions, and plan limits adequately. Only secondary details like paging interaction or the precise meaning of overlapping signals/badges are left implicit.

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 100% and three enums are self-documented, so the baseline is 3. The description largely restates schema content (badge=breaking equating urgent+big+world, sort modes) rather than adding syntax, format, or interaction detail beyond it.

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 ('latest Croatian news from all major portals') plus a differentiating scoping trait – deduplication to one item per story with coverage counts. An agent can distinguish this recency/aggregation tool from search_news, get_article, or get_city_news without opening a schema.

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?

Gives concrete intent-to-parameter mappings ('Use sort=most_covered for the biggest stories of the moment, most_read for what people read, badge=breaking for what is urgent'), which tells the agent when to reach for which knob. It never names an alternative sibling or states when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description contributes genuinely new behavioral context: the tool functions without authentication and degrades to free-tier session limits, which an agent needs to interpret the response scope.

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?

A single sentence, front-loaded with the primary return content, with the auth caveat tucked into a parenthetical. Nothing is redundant and nothing is missing.

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?

An output schema exists, so return-value detail is not the description's burden, and the tool takes no arguments. For a simple read-only introspection tool, the description supplies everything needed to invoke it correctly, including the keyless case.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. The description correctly does not invent parameter discussion.

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 names the exact resource and contents returned — the caller's plan, limits, and today's per-limit-group usage — with a specific verb-resource reading ('usage'). No sibling tool in the namespace (fetch, get_article, search_news, etc.) overlaps, so the agent can route to it unambiguously.

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?

Usage is implied rather than stated: the agent infers 'call this to check your quota.' The parenthetical does give a real condition — it works without a key and then reports the free MCP session's limits — but there is no explicit when-to-use/when-not versus alternatives, and no stated prerequisites.

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

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

Annotations already cover readOnly, idempotent, and non-destructive safety traits, so the bar is lower. The description adds real value beyond them: it explains that results include distance, place, kind, portal count, and every portal's link, and that filler is excluded by default—useful behavioral context the schema alone doesn't emphasize.

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?

Front-loads the core purpose and example before moving to filters and result contents. It is somewhat dense with examples, but each sentence carries functional information—no 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?

An output schema exists, so return values needn't be fully restated, and the description still summarizes the key result fields. Combined with full schema coverage and safety annotations, it is complete enough to call correctly; only explicit sibling differentiation is missing.

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 already 100%, so a baseline of 3 applies. The description adds meaning beyond the schema by noting place accepts Croatian names in any grammatical case ("u Zadru", "Splitu") and by giving a worked radius example, which directly clarifies the two trickiest params.

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+resource: 'News near a place in Croatia or near coordinates, within a radius in km,' with a concrete example. Its scope (geospatial radius retrieval) is distinguishable from siblings like get_news_map or fetch, though it does not explicitly name or contrast those alternatives.

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 closing sentence, 'Use for "what's happening near me / in <town>",' gives a clear positive use case. It does not state when this is the wrong choice versus alternatives such as get_city_news or search_news, so it stops short of explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld=false, so the safety burden is light. The description adds genuine behavioral detail beyond them: newest-first ordering, the 24-hour default window, and the fact that filler (horoscopes, quizzes, gossip, promos) is silently excluded unless include_filler is set. Return shape is not described, but an output schema 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?

Two sentences, both earning their place, with the resource description front-loaded before the urgent_only tip. The first sentence is quite dense with the coordinate/place/kind/reports enumeration, but nothing is redundant.

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?

With a full output schema and rich annotations, the description only needs to cover what those don't: default window, ordering, and the filler-exclusion behavior, all of which it does. The remaining gap is guidance on choosing this tool over the geo-adjacent 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 description coverage is 100%, so every parameter already carries its own explanation, and the description largely restates them (default 24 hours, urgent_only meaning). The one value-add is framing urgent_only as an 'emergency overview', but it does not clarify interaction between kinds and urgent_only or how limit interacts with the plan cap.

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 resource and scope: every geolocated news story in the last N hours across Croatia and the world, newest first, with coordinates, place, kind and reports. That framing distinguishes it from get_latest_news, search_news and list_stories without naming them. It stops short of an explicit sibling callout, so a 4 rather than a 5.

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?

One concrete usage trigger is given: 'Use urgent_only=true for an emergency overview (fires, crashes, floods…)'. There is no guidance on when to prefer this over the nearest alternatives such as get_nearby_news or get_city_news, so the routing decision is only partly supported.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is low. The description still adds real context beyond the annotations: the authoritative data sources, the Croatian scope, and the specific data points each recall carries. It does not mention pagination or result caps, but the limit param covers that.

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?

Two sentences with the purpose front-loaded and the source/field detail packed into a parenthetical. Dense but nothing is wasted; the only mild redundancy is re-listing search dimensions already in the schema.

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?

With an output schema present, the description needn't explain return values, yet it helpfully enumerates the fields anyway. Annotations carry the safety semantics and the schema fully documents parameters, so an agent has everything needed to invoke this correctly; only explicit alternative-tool guidance is missing.

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 100%, so the schema already documents q, lang, and limit. The description's 'Search by product, brand, store or hazard' and 'lang=en for English' largely restate the q and lang schema descriptions, adding little new syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource ('get_product_recalls' = product recalls) and immediately scopes it: Croatia, with named sources (HAPIH, EU RASFF, Safety Gate) and the returned fields (product, brand, stores, risk, reason, link). This is unmistakably distinct from every sibling, all of which are news/story/digest tools.

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 implies usage by listing the searchable dimensions ('Search by product, brand, store or hazard'), which tells the agent how to query, but never states when to reach for this tool versus alternatives, nor any exclusions or prerequisites. Adequate but no explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's only behavioral addition is the implicit prerequisite that the story must be 'followed', and it otherwise restates return content that the output schema already carries.

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?

Two compact sentences: the retrieval scope and returned fields come first, the intended use case second. Every clause is load-bearing, though the trailing 'plus the location' is slightly vague about whose location is returned.

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?

An output schema exists, so return structure need not be explained, and annotations cover the safety profile; the description still supplies the missing provenance and purpose. It does not mention pagination or limits on long timelines, a minor gap for a historical-list tool.

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?

With only one parameter and 100% schema coverage, the baseline is 3, but the description adds real value by naming three concrete sibling tools that produce a valid slug, whereas the schema only cites a raw endpoint and a URL path. That provenance guidance is meaningfully beyond the schema text.

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 — retrieving the full timeline of a followed story by slug — and enumerates the returned content (stages in order with label, time, summary, per-portal report, location). Naming the sibling sources for the slug (list_stories, get_article, research_topic) makes it clearly distinguishable from the article- and search-oriented siblings.

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?

Gives explicit usage context ('Use to explain how a story developed') and states where the slug comes from, which is the main prerequisite for calling it. It stops short of saying when NOT to use it (e.g. a single-article read is get_article), so it is clear but not fully exclusive.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only a light hint about return content (article counts and links) and the geographic/daily currency of the data, which is modest value beyond the structured fields.

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?

Two compact sentences, front-loaded with what the data is before the usage cue. Every clause carries information and nothing is padded.

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?

With an output schema present, return structure need not be spelled out, and the zero-param, read-only nature means no auth or side-effect detail is required. Purpose and usage are covered; the only gap is sibling differentiation among the numerous adjacent news tools.

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 tool takes zero parameters, so there is nothing to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies no input is required to obtain the current trend list.

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 concrete resource and scope: trending topics from Croatia right now, including article counts and links. It is distinguishable from siblings like get_latest_news or search_news by the 'trending' framing, though it does not explicitly contrast itself with them.

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 an explicit trigger phrase ("what's trending") and a secondary use case (suggesting follow-up questions). It gives clear when-to-use context but names no alternatives or when-not conditions among the many sibling news tools.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true), and the description adds that output is 'written summary...with links' and the time window Monday-Sunday. It does not disclose pagination, rate limits, or return format details beyond what the output schema likely provides.

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?

A single dense sentence with zero waste, front-loading the core purpose and time window before the parameter behavior. Every clause earns its place.

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?

Complete for a read-only digest tool with an output schema and full parameter coverage. The description supplies the domain-specific context (Croatia weekly summary) an agent needs to route correctly, though it does not detail the return structure.

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 100%, so the schema already documents both parameters fully. The description restates the date and croatia_only semantics but adds no syntax or format details beyond the schema baseline.

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 (get), resource (weekly digest), and distinctive scope (Croatia, Monday-Sunday) that clearly separates it from siblings like get_daily_digest and get_latest_news. The mention of 'by section, with links' further specifies the content shape.

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?

Explains when to use croatia_only=true and that passing nothing returns the latest, but does not explicitly name alternatives (e.g., get_daily_digest for daily coverage). The usage context is clear without naming competitors.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and freshness-of-source are covered structurally. The description adds the useful detail that entries carry both Croatian and English names, but says nothing about staleness, completeness, or whether the list can change over time.

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?

A single sentence, front-loaded with the resource, followed by the usage note. The inline '…' examples add useful color without bloating, though the dual enumeration makes the sentence slightly dense.

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?

With an output schema present, the description needn't detail return values, and it still communicates the two enumerations and their bilingual naming. An agent has enough to decide to call it and how to use 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 tool takes zero parameters, so the baseline is 4. The description correctly explains that the output is used to populate filters of other tools, which is the only semantic an agent needs here.

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 what the tool returns: article categories and map story kinds with Croatian and English names. It implicitly distinguishes itself from the retrieval siblings by being a reference/enumeration lookup, though it never uses an explicit verb like 'list' to anchor the purpose.

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?

It gives the condition for using it — 'for filters of the other tools' — which tells the agent this is the way to discover valid filter values before calling siblings. It does not name a specific alternative or an explicit when-not, but for a singleton reference tool there is little ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed openWorldHint, so the safety and idempotency profile is fully covered by structured data rather than the description. The prose adds the useful fact that this is a fixed, static catalogue of outlets (an enumeration, not a live query), which is mild added value but not rich behavioral disclosure.

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?

A single sentence that leads with what the tool produces and trails into the reason to call it. No filler, nothing repeated from annotations, and the downstream-use clause is the payoff rather than padding.

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?

With an output schema present, return-value formatting need not be explained, and with zero parameters there is no input contract to document. The description supplies the one genuinely useful fact an agent needs — that these slugs feed the filtering parameters of get_latest_news and search_news.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The prose correctly avoids inventing inputs and instead describes the content shape.

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 the specific resource (the Croatian news portals the service aggregates) and what is returned with it (slugs), and it distinguishes itself from sibling listers like list_categories and list_stories by naming the actual domain content. An agent knows exactly what this tool enumerates without opening the schema.

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?

Explicitly routes the agent: the slugs exist 'for filtering get_latest_news or search_news by portal', naming the two consumer tools and the condition that selects them. That is concrete when-to-use guidance rather than an implied context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavior beyond that: results are ordered newest-development-first and filler content is excluded by default. This is useful non-obvious context that the schema/annotations alone would not convey.

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?

Three sentences, front-loaded with the concept definition before filters and the follow-up step. No wasted text. The parenthetical Croatian gloss is a minor flourish but harmless.

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?

With an output schema present, the description need not explain return values, and it correctly omits them. It covers concept, filtering, ordering behavior, and the next-step workflow, leaving little an agent needs to infer. Slightly short on how this tool relates to other news-listing 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 description coverage is 100%, so the schema already documents all six parameters in detail. The description touches on filtering by text, category, and period, which mirrors the schema, and echoes the default ordering. It adds little beyond what the structured fields provide, so the baseline 3 is appropriate.

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 (list) and resource (stories) and goes further by defining what a 'story' actually is — a multi-day timeline of stages, with a concrete example. It explicitly routes to get_story_timeline, distinguishing that sibling. It does not, however, contrast against other listing siblings such as get_latest_news or search_news.

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?

Gives clear context for when this tool applies (tracking stories across days/weeks) and how to narrow results (text, category, period). The closing instruction 'Then call get_story_timeline with a slug' supplies concrete follow-up guidance. No explicit when-not or alternative-tool exclusion is provided.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral value by disclosing that this is a broad fan-out aggregation returning five distinct result kinds in one call, which is not inferable from the annotations alone.

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?

Front-loaded with the tool's identity, then the input and the enumerated outputs, closing with a crisp usage hook. The output enumeration is dense but each item earns its place by distinguishing the aggregation scope; only the colon-heavy list slightly slows reading.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description supplies the aggregation semantics and a use-case trigger; what remains missing is any hint that results are bounded by plan archive/limits, though the schema covers that.

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 100%, so the schema already documents q, days, limit, and include_filler. The description restates the query semantics (person, place, event, topic) but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

Names a specific verb (research) and resource (topic/question) and enumerates the aggregated result types (articles, stories, map locations, daily summaries, timeline), which clearly separates it from single-purpose siblings like get_story_timeline or search_news.

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?

"Best first call for 'what happened with X'" gives clear positive routing guidance for when to reach for this tool over the narrower siblings. It stops short of naming a specific alternative to use instead when a narrower call is preferable, so it is not a full when/when-not statement.

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

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

Annotations already establish read-only, idempotent, non-destructive, and notably openWorldHint=false. The description adds the domain constraint (Croatian places only) and the fact that inflected grammatical cases are accepted, which the agent could not infer from annotations alone.

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?

Two sentences, no padding, with the domain scope front-loaded and the usage rule immediately after. Every clause carries information.

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?

An output schema exists, so return values need no elaboration, and both input modes are covered. The only gap is behavior on ambiguous or unmatched names (multiple candidate towns, no result), which the agent would have to discover at runtime.

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 100%, so the baseline is 3. The description earns an extra point by making the mutually-exclusive usage pattern explicit (name OR lat+lon), which is not obvious from a zero-required-parameter schema that simply marks lat/lon as "or a point".

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 (resolve) plus resource (Croatian place name), and explicitly covers both directions of the mapping: name -> coordinates/kind/county and lat/lon -> nearest town. This is far more specific than the sibling tools, none of which do geocoding.

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?

"Use when the user names a place and you need coordinates, or to tell a user where coordinates are" gives clear triggering conditions for both modes. It does not name an alternative tool or state exclusions, but no sibling overlaps this function, so the guidance is adequate without them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description usefully discloses semantic matching and the id-to-fetch handoff. However, it says nothing about result limits, ordering/recency, or whether 'followed stories' are included by default or on some condition, so behavioral coverage is partial.

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?

Three short sentences, front-loaded with purpose before the alternative and the follow-up workflow. The middle sentence partly restates the result shape that the output schema already carries, a small redundancy, but nothing is verbose.

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 single-parameter search with an output schema and full annotation coverage, the description supplies purpose, alternative routing, and the next step, which is close to sufficient. The remaining gap is sibling disambiguation from search_news, which an agent could plausibly confuse with this tool.

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?

Only one parameter, and schema description coverage is 100% (the schema already states 'What to look for, ideally in Croatian' with an example). The description's 'by meaning' reinforces the natural-language intent but adds no syntax, filtering, or format guidance beyond the schema, so the baseline 3 applies.

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 (Search) plus resource (Croatian news and followed stories) and adds the crucial qualifier 'by meaning', which tells the agent this is semantic rather than keyword search. It distinguishes itself from research_topic and fetch, but says nothing about how it differs from the near-identically named sibling search_news, leaving that ambiguity unresolved.

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?

'Use for open questions; research_topic gives a richer overview' gives an explicit when-to-use condition plus a named alternative with its trade-off. It also prescribes the follow-up step (pass an id to fetch for full text), though it omits any exclusion relative to the search_news sibling.

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

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

Annotations already carry the full safety profile (readOnly, idempotent, openWorld=false, non-destructive). The description adds genuine behavioral context beyond that: results are 'newest-relevant first' and each carries signals and badges. It stops short of noting default limits, pagination, or archive constraints, so it is solid but not rich.

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?

Three tight sentences, front-loaded with the core 'search by meaning' statement followed by language guidance and the filter enumeration. Little waste, though the badge list appears twice (query filter and return values), which is mildly redundant.

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?

With an output schema present and 100% schema coverage, the description need not explain return values, and it correctly focuses on language guidance and filtering. It is nearly complete for a search tool, missing only ordering/pagination clarification relative to the sort parameter.

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 100%, so every one of the ten parameters is already documented in the schema, including enum meanings for badge and category. The description restates the same filter list and adds only example query strings, which the schema's 'q' description also provides. Baseline 3 is appropriate.

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 ('Search Croatian news by meaning (semantic + text)'), which already distinguishes it from listing tools like get_latest_news. It does not, however, explicitly contrast itself with the sibling 'search' or 'research_topic', so sibling differentiation is left implicit.

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 useful invocation guidance ('Write the query in Croatian when you can... English works too') and enumerates the optional filters, but never states when to prefer this over sibling search, research_topic, or get_latest_news. Usage context is implied rather than explicit.

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