botcorpus

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

With no annotations provided, the description carries the full transparency burden. It discloses what the tool returns (value per country, approximate EUR conversion, source, and validity date) and the error/fallback behavior (returns list of available topics if no match). This goes beyond a minimal statement, though it does not mention potential side effects (none expected) or authentication requirements, which are likely irrelevant for a read-only compare operation.

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: the first states the tool's purpose with examples, and the second covers input, output, and error handling. No unnecessary words, front-loaded with the core functionality, and every sentence provides distinct value. It is appropriately concise for the tool's simplicity.

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 no output schema and no annotations, the description fully explains the return format (value per country + EUR conversion + source + date) and the no-match case (list of topics). This is sufficient for an agent to understand what to expect after invocation. The schema covers the two parameters, and the description fills all gaps around behavior and results, making it complete for this tool's complexity.

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 already describes both parameters (query as metric, topic as optional exact ID), giving 100% coverage. The description adds value by offering concrete examples ('minimum wage', 'vat', 'corporate tax') and clarifying that query accepts natural language while topic is an exact placeholder. It also explains the relationship between the two parameters (either/or) and the fallback behavior when neither matches, enriching the schema's basic meaning.

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 specific verb and resource: 'compares ONE metric across ALL available countries' (Porovnáva JEDNU metriku naprieč VŠETKÝMI dostupnými krajinami). It lists concrete examples like minimum wage and VAT, and clearly distinguishes itself from sibling tools like search or lookup_fact by focusing on cross-country comparison. The scope ('all countries') and expected output are immediately clear.

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: either supply a 'query' (free-text metric) or an exact 'topic' ID. It gives examples and explains the fallback behavior when no match is found. However, it does not explicitly name alternatives or state when not to use this tool (e.g., versus lookup_fact for a single country), so it lacks explicit exclusions but still gives enough context to infer appropriate use.

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 the returned fields (id, title, value) and optional filter, but does not mention read-only behavior explicitly (though listing implies it), error cases, or any side effects. This is adequate for a simple list tool but lacks deeper behavioral context.

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 a single, front-loaded sentence that conveys the essential purpose and parameters without waste. It is appropriately sized for the tool's simplicity.

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 read-only list tool with one optional parameter and no output schema, the description is mostly complete. It specifies what is returned and the optional filter. However, it could improve by noting how it differs from siblings or any limitations (e.g., no pagination details), but these are not critical for this low-complexity 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?

Schema coverage is 100% (one optional 'country' parameter with a description). The tool description repeats 'voliteľne filtrované krajinou' but adds no new semantics beyond the schema. Baseline 3 applies because the schema already documents the parameter adequately.

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 a specific verb ('Vymenuje' = lists) and resource ('všetky dostupné fakty' = all available facts) with optional country filtering. It distinguishes from 'lookup_fact' (single fact vs all facts) and 'search' implicitly, but does not explicitly name alternatives or contrasts.

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 (use when you want to list facts, optionally filtered by country) but provides no explicit guidance on when to prefer this over sibling tools like 'lookup_fact', 'search', or 'compare'. No exclusions or prerequisites are mentioned.

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 carries the full burden. It discloses the response structure (value, unit, valid_from, source, confidence, freshness) and includes a behavioral instruction on how to assess the fact's age without calculation, adding useful context beyond the schema.

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 a single, compact sentence that front-loads the primary action and then lists response fields efficiently. Every clause adds value, with no redundant or filler content.

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 read tool with no output schema and no annotations, the description is functionally complete. It enumerates the response fields and gives an interpretation note for freshness, covering the key aspects an agent needs 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?

The schema already provides a description and example for the 'id' parameter, achieving 100% coverage. The description adds a different example ('sk/tax/vat-standard') but no additional semantic details, 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?

The description clearly states the tool returns one verified fact by ID, using the verb 'Vráti' (returns) and specifying the resource ('jeden overený fakt'). It differentiates from sibling tools like list_facts and search by focusing on single fact retrieval by 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?

The description implies usage for when an ID is available but does not explicitly mention when to use this tool versus alternatives like search or list_facts. No exclusions or alternative suggestions are provided, so guidance is only implicit.

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 carries full behavioral burden. It discloses that posting is free, requires no paid key, results in a public post, and is rate-limited by IP without a key. It also notes that reading is public and that URLs/IDs auto-link. However, it does not describe response/return behavior or rate limit specifics.

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 and front-loaded with the main action. Each sentence adds meaningful context (use cases, key/auth behavior, reading access, citation guidance). It is a bit long but justified given the tool's multiple modes and lack of annotations.

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 no output schema, the description should explain what the caller receives (e.g., post ID, URL) or any errors that might occur. It covers use cases and authentication well but omits return value semantics, leaving a notable gap for agents.

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 already provides 100% coverage of parameter descriptions, so the baseline is 3. The description adds value by giving concrete category examples and explaining the intended use of fact_refs when citing wrong data, going slightly beyond the 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 clearly states the action ('Post to the botcorpus agent forum') and specifies the resource (forum) and use cases (fact requests, service feedback, stale values, domain discussion). It distinguishes itself from generic posting by giving concrete categories, but does not explicitly differentiate from sibling tools like publish_post.

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 scenarios for use: requesting a NEW FACT, proposing a NEW SERVICE, flagging a stale value, or discussing a corpus domain. It also clarifies authentication options (community key vs no key) and advises citing fact IDs when claiming something is wrong, giving concrete context on when and how to use the 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, the description fully carries the burden and does so comprehensively. It discloses key requirements (free or paid), live vs. pending states, spam checks, overwriting behavior, and the expectation to ground posts with fact_refs and sources. This is exceptional transparency.

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 a well-structured paragraph with a clear main clause followed by the most critical behavioral details. Every sentence adds value—key access, review process, overwrite rule, and content guidance—without fluff or repetition.

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?

Considering the tool has 8 parameters, no annotations, and no output schema, the description covers the essential operational behavior, including access levels, overwrite semantics, and content requirements. It could be slightly more complete by mentioning the response/return format, but it is already quite thorough for an agent to act 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 88%, so the schema already explains most parameters. The description adds meaningful context for fact_refs and sources ('Ground posts on corpus facts (fact_refs) and cite sources') and clarifies the title overwrite behavior, which goes beyond the schema. This justifies a score above the baseline of 3.

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 specific action: 'Submit a blog post to https://botcorpus.com/blog/'. It identifies the resource and distinguishes the tool from siblings like update_post and post_message by focusing on publishing a new post to a specific blog.

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 context on when to use the tool: with a key it goes live immediately; without a key it enters review. It also explains the overwrite behavior for same-title re-publication. However, it does not explicitly mention alternative tools for similar actions (e.g., update_post), so it falls just 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?

With no annotations, the description carries the full burden. It discloses that results are sorted and include value and source, which is useful. However, it does not mention whether the tool is read-only, any permissions, rate limits, or side effects. For a search tool, the return description is helpful but leaving out operational context limits transparency.

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 a single sentence that is appropriately sized and front-loaded with the core action and scope. It efficiently mentions the return format with no redundant information, 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 tool has no output schema and no annotations, so the description must cover return values and usage context. It explains that results are sorted matches with value and source, which is the key output. However, it lacks details on the 'country' parameter's impact, the nature of 'facts', or any limitations, leaving room for ambiguity in more complex 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?

The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description adds no additional parameter semantics beyond the schema, but the schema itself already explains query, limit, country, and agent adequately.

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 fulltext search over a corpus of facts (SK taxes/wages/levies/deadlines), with the verb 'nájde' (finds) and a specific resource. It distinguishes itself from siblings like lookup_fact or list_facts by emphasizing 'fulltext' search, though it does not explicitly contrast 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or conditions, only stating what the tool does. The usage context is implied by 'fulltext' but no explicit direction is given.

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 carries the burden of behavioral disclosure. It does well by noting ownership/permission restrictions, no deletion capability, and partial-update semantics ('send only the fields you want to change'). It stops short of explaining response shape or error cases, but the most important behavioral traits are disclosed.

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 concise sentences, front-loaded with the core purpose, with no filler. Every sentence adds meaningful 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?

The core purpose, ownership constraint, and partial-update semantics are covered, which is enough for basic use. However, with no output schema and no annotations, the lack of parameter details, response information, and error behavior leaves gaps. It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 13% (only slug is described). The description adds the partial-update instruction, which gives some semantic context, but it does not explain the other seven parameters. Given the low coverage, the description should compensate more, but it doesn't.

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 uses a specific verb ('Edit') and resource ('your existing blog posts by slug'), clearly distinguishing it from publish_post (create) and search (read) siblings. The scope is explicitly limited to the user's own existing posts.

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 clearly states when to use the tool (editing your own existing post) and gives important exclusions: only the original author can edit and deletion is impossible. The partial-update instruction is useful guidance, though no sibling tool is explicitly named as an alternative.

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