BrunoSan AI News Intelligence

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds real value beyond annotations by disclosing the behavioral trait that a human-readable page is published on brunosan.de and is included via published_url, plus the digest composition (stats, top-5 clusters). No rate limits or other constraints disclosed, but the output-context addition is meaningful.

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?

Well front-loaded: purpose in the first sentence, followed by use cases, example queries, then args/returns. The structure is logical and every section earns its place, though the Returns block is fairly detailed and the three example queries are somewhat redundant with the stated use cases. Slightly long but efficiently organized.

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?

Covers what, when, how to call (date param), and precisely what comes back (date, published_url, stats, top_clusters with nested fields). With annotations covering the safety profile and the description itself detailing the return shape, little is missing for a read-only digest tool. The sole notable gap is the unmentioned api_key parameter and no explicit rate-limit or freshness caveat.

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 Args section explains the date parameter ('Date YYYY-MM-DD, empty = latest available day') and reinforces the return semantics, though the schema already documents date identically. Notably, api_key is entirely absent from the description's Args section — an agent reading only the description wouldn't learn it's a required input. The description does add interpretive value via the Returns section mapping fields like stats and top_clusters.

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 precise specifier — 'Complete daily digest: all clusters, top articles, and statistics for one day' — naming both the resource (one day's AI news) and scope (clusters, articles, stats). It adds 'The full overview of a day's AI news' which clearly separates it from siblings like news_search, news_trending, and news_risk_radar without needing to open their schemas.

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 concrete usage context — 'ideal for morning briefings, newsletter preparation, or "summarize today's AI news"' — plus three illustrative example queries covering today, a past date, and a specific calendar day. This is clear context for when to invoke it, though it never names sibling alternatives or states when NOT to use it, lacking explicit exclusions.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail: the exact composite formula, the (+1) smoothing rationale, the role-specific filters, and the auditability requirement. This is a strong disclosure of how rankings are produced and what the response envelope contains.

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 longer than average, but the formula, role scopes, and example queries all serve a functional purpose and are organized in clear sections. The front-loaded formula and role explanation give the key information first; the examples could be slightly trimmed but are not wasteful.

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 moderate complexity, the description is complete: it explains the ranking formula, role scoping, parameter semantics, filtering logic, and the JSON return structure. An agent has enough information to select the right role, construct a valid query, and interpret the ranked clusters without needing external 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?

The description adds important meaning beyond the schema by defining each role's filter semantics and showing role-based example queries. It does not repeat every schema detail like limit bounds or api_key, but the schema already covers those, so the description's role-scope detail is the valuable differentiator.

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 verb and resource: AI news clusters ranked by a transparent composite formula for role-specific briefs. It clearly differentiates from siblings by emphasizing role-aware filtering and the auditable composite formula, rather than generic news retrieval or 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 provides clear usage context through role scopes and concrete example queries for each intended audience (CDO, CTO, CEO, Compliance). It does not explicitly name sibling tools or state when not to use it, but the role-aware framing and examples make the intended invocation context unambiguous.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful output semantics such as total_mentions and co_occurring_entities, but does not disclose behaviors like authentication requirements, rate limits, or how entity matching/normalization works. This is adequate given annotations, but not exceptional.

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-organized into overview, best-for, examples, args, and returns. Every section adds practical value, and the example queries make usage immediately concrete without excessive verbosity.

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 tool with one required parameter, an existing output schema, and strong annotations, the description covers invocation, input semantics, output structure, and usage scenarios. An agent has enough information to call it correctly and interpret 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 description's Args section clearly explains entity with examples and limit with a default value, which compensates for the reported low schema description coverage. It does not mention the api_key parameter, but that is documented in the schema and has a default. Overall, the description adds meaningful meaning beyond the raw schema.

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 a precise resource ('a company, product, person, or region') and lists exactly what is returned: mention count, recent articles, entity type, and co-occurring entities. This clearly differentiates it from siblings like news_search or news_trending because it is an entity-profile tool, not a general search or trend tool.

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 'Best for' line plus concrete example queries give an agent clear context for when to call this tool: researching a specific entity or discovering co-occurrence partners. It does not explicitly name alternatives or say when not to use it, so it misses a full exclusion clause, but the usage 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=true and idempotentHint=true, and the description aligns with a read-only statistics operation. It adds a full description of the return payload including db_stats fields and top_sources, and explains aliases (e.g., unique_sources as alias for historical_article_domains). No contradiction with 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?

The description is well-structured with summary, usage, examples, args, and returns. However, it contains internal noise such as 'vollstaendiges Schema, BSN-PATCH docstring 20260731_2145' and German field translations that do not serve the agent. It is longer than necessary without each sentence earning 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?

The output schema is complex and the description covers it thoroughly, listing every db_stats field and their meanings. Example queries and limits are provided. Missing api_key mention is a small gap, but the overall description is sufficiently complete for correct invocation.

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 description documents limit with its default value, matching the schema, but omits the api_key parameter entirely. Given the context signal of 0% schema description coverage, the description only partially compensates by covering one of the two parameters. The missing api_key means an agent relying on the description alone wouldn't know about authentication.

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 clear verb and resource: 'Statistics for canonical source objects, historical article domains and feed operations' and 'Shows which domains contribute the most articles'. It is easily distinguished from siblings like news_search or news_get_entity by focusing on aggregate source stats, and the 'Best for' examples clarify the exact use case.

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?

Explicit usage context is provided: 'Use this to understand the data foundation behind the news answers, or to verify source diversity and coverage' plus example queries. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to route to this tool for source-level statistics.

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 and idempotentHint, and the description adds context beyond them: it discloses the calculation, states that the formula is open and auditable, and specifies the returned JSON fields including date, formula, filters_applied, count, and clusters. For a read-only ranked report, this is strong 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?

The description is front-loaded with the core purpose and formula, then organized into Args, Returns, and examples. The five example queries are useful for an agent deciding how to phrase inputs, though somewhat repetitive. Overall, it is structured and readable without significant waste.

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 complexity—five parameters, a nested input object, a scoring formula, and a structured response—the description covers the logic, filter behavior, response shape, and representative use cases. Nothing critical is missing for an agent to select and invoke it correctly; authentication is handled by the api_key parameter in the schema.

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?

Although the schema already documents each parameter, the description clarifies their semantic role by linking min_official_sources and min_compliance_signals to the formula components and by demonstrating usage through example queries. It also clarifies that an empty date means the latest available day and that the response includes component counts. This adds meaning beyond the raw schema.

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 precise statement—'Active risk and compliance signals ranked by combined_risk_score'—and exposes the exact scoring formula. This clearly distinguishes it from generic news search tools by anchoring on risk/compliance aggregation and ranked output. The explicit formula removes ambiguity about what the tool computes.

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 provides concrete use scenarios (daily risk scan, delta report for weekly risk committee, compliance-signal filtering) and positions the tool as the AI-news equivalent of the Regulatory MCP's reg_score, covering all AI news rather than regulatory documents. However, it does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of full exclusionary 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, and destructiveHint, and the description is consistent with them, so no contradiction. It adds value beyond annotations by specifying search scope (titles and summaries of the live corpus), pagination semantics, and the exact return envelope (total_found, has_more, next_offset, articles), which helps an agent know what to expect from the call.

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?

Well-structured with a one-line summary, scope, best-for guidance, illustrative example queries, and separate Args/Returns sections. Each section earns its place; the examples actively teach query style 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?

For a read-only, idempotent search tool with a return format fully specified, the description is nearly sufficient. The main gap is the undisclosed api_key parameter, which an agent needs to know about for authentication; the example queries and pagination contract cover most operational scenarios.

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 schema description coverage reported at 0%, the description carries the burden and partially compensates: it explains query (any language), limit (default 10), and offset (default 0) with types and defaults. However, it omits api_key entirely from the Args list, and does not restate constraints like limit's 1-50 range or query's length bounds, leaving the parameter picture incomplete.

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 a specific verb and resource ('Full-text search across the current live AI and technology news corpus') and adds scope ('Searches titles and summaries of all stored articles'), which is clear and actionable. It does not explicitly name or contrast with siblings like news_search_entities, so some differentiation is left to inference rather than stated.

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 clear usage context via 'Best for: finding recent developments on a topic, researching a company, product or trend, discovering coverage of specific events,' plus three concrete example queries that convey intended scenarios. It lacks explicit exclusions or alternative routing (when not to use this vs. news_search_entities or news_get_entity), 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns 'mention_count' and can filter by type, which is useful context. However, it does not discuss authentication requirements (api_key) or any rate limits. Since the annotations cover the safety profile and the description adds some but not rich behavioral detail, a 3 is appropriate.

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 somewhat long but well organized. It front-loads the purpose and usage guidance, then provides example queries, and finally lists arguments and return format. Each section serves a purpose; the example queries are especially helpful. While it could be tightened, it is not wasteful and remains readable, so a 4 is appropriate.

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 covers the tool's purpose, usage examples, argument details, and return format. It also explains the relationship with news_get_entity. The only notable gap is the lack of mention of the api_key authentication parameter, but that is present in the schema. For a read-only search tool with a clear output format, the description is largely complete and an agent can call it 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?

The schema provides descriptions for all properties (query, type, limit, api_key), so the baseline is 3. The description adds value by listing the three main parameters (query, type, limit) with their purposes and default values, and by providing example queries that illustrate how to use them. It omits api_key, but that is covered in the schema. The concrete examples and the mention of default limit (20) go beyond the schema's basic descriptions, justifying 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's function: 'Search across the current entity index: companies, people, products, and regions.' It specifies the verb (search), the resource (entity index), and the scope (four entity types). It also distinguishes itself from sibling tools by noting it is 'useful for discovery before using news_get_entity,' making it easy to tell apart from a general news search or a specific entity lookup.

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 explicit guidance on when to use the tool: 'Useful for discovery before using news_get_entity' and gives concrete example queries like 'is [company X] in the database?' It names one alternative (news_get_entity) but does not explicitly exclude other siblings such as news_search. It implies the use case but lacks a comprehensive when-not-to-use statement, so it earns a 4 rather than 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description correctly focuses on additional context: scores are deterministic, reproducible, auditable, UUID-stable, and read from article_fact_profile using the currently activated pipeline version. This adds genuinely useful behavioral nuance beyond the annotations, with no contradiction.

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 first paragraph is tight and front-loaded, and the Args/Returns sections are clearly structured and scannable. The five example queries add useful context but are somewhat redundant, and one is misleading, so the description is good but not maximally concise.

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 complexity — seven score types, multiple filters, nested input, and a rich output shape — the description covers the score set, filtering semantics, quality flags, lookback window, limit, and full JSON return format. The main gaps are the omitted api_key parameter and the misleading intersection example, but overall the description is largely complete for a read-only tool with rich schema and annotations.

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 schema_description_coverage reported as 0%, the description must carry parameter meaning, and it does explain score_type, min_score, since_days, quality flags, and limit in plain language. However, it omits the api_key parameter entirely and does not state defaults for limit, score_type, or the exclude_* booleans, leaving the agent dependent on the schema for those details.

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 does: it computes seven deterministic 0–100 signal scores per article and filters articles by a chosen score_type and minimum value. The 'computed without LLM / Reproducible / Auditable' framing helps distinguish it from siblings like news_search and news_trending, even though it never explicitly names an alternative.

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 example queries provide concrete usage contexts: regulation signals, risk above 80, CFO cost briefings, CTO operational awareness. However, it never says when not to use it or which sibling tool to prefer, and the third example ('both high regulation_relevance AND high business_relevance… intersection') implies a multi-score AND capability that the Args section contradicts by requiring a single score_type.

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 behavior. The description adds useful context by explaining that clusters are formed by the BrunoSan pipeline from daily article intake, and ranked by burst_score with article_count as tiebreaker. No contradictions with 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?

The description is front-loaded with the core concept and then organized into best-for, examples, args, and returns. It is a bit long, but each section earns its place and supports agent decision-making.

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 trending tool, the description covers data source, ranking logic, parameter behavior, and return fields. It could be more explicit about the api_key requirement and how it complements sibling tools, but nothing essential 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?

The Args section explains date format, empty-date behavior, and default limit, but much of this is also present in the input schema. The api_key parameter is not described in prose, and the description mostly restates schema-level details rather than adding deeper 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?

The opening sentence precisely identifies the resource ('top topic clusters for a given day') and the conceptual frame ('what is moving the AI world right now?'). The ranking criteria and returned fields make it clearly distinct from siblings like news_search or news_daily_digest.

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 'Best for' section and example queries give explicit, actionable use cases: daily briefings, trend detection, and 'what happened in AI today?'. It does not explicitly state when not to use alternatives, but the guidance is strong enough to scope selection.

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