Svodka — Bulgarian News

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

No annotations are provided, so the description bears full responsibility. It discloses that the tool returns a full summary and sources, implying a read operation. However, it does not mention any limitations, required permissions, or error conditions, leaving gaps for a simple get 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?

The description is very concise (two sentences) and front-loaded with the core functionality. The first sentence is in Bulgarian, which may slightly reduce clarity for non-Bulgarian agents, but overall it is efficient and well-structured.

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 (one parameter, no output schema), the description covers the key aspects: what it returns (full summary and sources) and how to obtain the ID. It is sufficient for an agent to use the tool correctly.

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 already describes the id parameter thoroughly—including its type, source from link, and example. The description adds no additional parameter details beyond what the schema provides, so 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?

The description clearly states the tool returns the full summary and sources of a specific news article by its numeric ID. It distinguishes itself from sibling tools like get_leading_news and search_bulgarian_news by specifying that it expands one story after those tools provide an ID.

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 tells the agent to use this tool after search_bulgarian_news or get_leading_news to expand a story by the ID from its link. This provides clear when-to-use guidance and differentiates from siblings.

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?

No annotations are provided, so the description carries full burden. It discloses that results are importance-ranked, clustered, and include reason and outlet count. However, it does not mention any behavioral traits like read-only nature, cache, or time constraints beyond 'for the day'. Adequate 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?

The description is two sentences in Bulgarian followed by an English explanation. It is concise, front-loaded with the main purpose, and contains no extraneous information. Every sentence adds value.

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 simple tool with one optional parameter and no output schema, the description explains the output sufficiently (ranking, clustering, reason). It could be more explicit about the time scope (e.g., 'for the day'), but the title already covers that. Overall, it is complete enough.

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 already provides 100% coverage of the single parameter (limit) with description, min, max, and default. The tool description does not add any additional parameter semantics beyond what the schema 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?

The description explicitly states it returns an importance-ranked leaderboard of today's leading Bulgarian news, clustered across outlets with reasons and outlet counts. This clearly differentiates from siblings like get_article (single article), list_recent_news (recent news without ranking), and search_bulgarian_news (search).

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 includes an explicit usage directive: 'Use when asked what the top, leading, or breaking news in Bulgaria is right now.' It does not provide explicit when-not-to-use or compare with siblings, but the context is clear.

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?

With no annotations, the description discloses key behaviors: chronological order (newest first) and cursor pagination. However, it does not mention any limitations or side effects, which is acceptable for a read-only list tool, but a 4 reflects minor room for more detail.

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 concise at two sentences with key information front-loaded. A point is deducted for mixing languages (Bulgarian and English), which could cause minor confusion for an English-language AI agent.

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?

The description does not explain the return format or field structure, which is needed since no output schema is provided. It mentions pagination but lacks details on response content (e.g., titles, summaries). This gap leaves the agent with incomplete context.

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% with clear descriptions for both parameters (limit and cursor). The description adds 'cursor pagination' context but no additional parameter meaning beyond the schema, so 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?

The description explicitly states it returns the latest news in chronological order (newest first) with cursor pagination, and contrasts with searching specific topics via sibling tool, making the purpose clear and distinct.

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 a clear when-to-use directive: 'Use to browse the latest headlines rather than search a specific topic,' implicitly guiding against using for topic-specific search, which is handled by the sibling tool.

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?

With no annotations provided, the description must fully disclose behavior. It reveals that results are summarized stories with source outlets and canonical links, and suggests semantic search. However, it does not mention any behavioral traits like caching, rate limits, or real-time nature, leaving some gaps.

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 extremely concise yet informative, using two languages (Bulgarian and English) to front-load the purpose. Every sentence adds relevant detail without redundancy, making it easy to parse quickly.

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 (2 parameters, no output schema), the description provides strong context: specific news sources, supported languages, and output summary. It is largely complete, though additional details on result ordering or coverage latency could improve it.

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 input schema covers both parameters (query and limit) with clear descriptions. The description adds value beyond the schema by explaining that queries work best in Bulgarian and providing example queries, as well as clarifying the output format (summarized stories with links). This enhances 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 clearly states the tool performs semantic search over aggregated Bulgarian news from specific sources, and mentions it returns summarized stories with links. However, it does not explicitly distinguish itself from sibling tools like get_article or list_recent_news, which provide context but are not directly differentiated.

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 advises using it for any question about current events in Bulgaria and notes queries work best in Bulgarian. It provides clear context for when to use, but lacks exclusions or alternatives, such as when to prefer sibling tools like get_article for a specific story.

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