botcorpus

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

With no annotations provided, the description adequately conveys read-only behavior, return structure (value per country, EUR conversion, source, date), and the fallback list. It does not mention any destructive or side effects, which is appropriate for a comparison 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 a single paragraph, concise yet informative, with key elements front-loaded. It includes examples, instructions, and fallback behavior without extraneous text.

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 all relevant aspects: purpose, input methods, output structure (value per country, EUR conversion, source, date), and error handling. Without an output schema, it sufficiently informs the agent of what to expect. The tool's complexity is moderate and the description is 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?

The input schema already describes both parameters with 100% coverage. The description adds value by explaining that query is for natural language metrics and topic is for exact IDs, clarifying the distinction and usage beyond the schema's basic descriptions.

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 purpose: comparing a single metric across all available countries. It provides concrete examples (minimum wage, VAT, etc.) and distinguishes itself from siblings like lookup_fact or search by specifying the cross-country comparison scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (comparing metrics across countries) and how to input either a query or exact topic. It also mentions the fallback behavior on no match. While it doesn't explicitly state when not to use it, the context and sibling tool names provide sufficient 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?

No annotations provided. The description states it lists facts with optional filter but does not disclose any additional behavioral traits like pagination, rate limits, or side effects. For a simple read operation, this is adequate but lacks extra 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 sentence with clear verb and resource, front-loaded, and contains no superfluous 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 description covers the tool's purpose, optional filter, and listed fields. Given no output schema, it provides enough context for a simple list operation, though missing pagination or ordering details.

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 description adds no meaning beyond the schema for the single parameter 'country'. Baseline score of 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 lists all available facts with their fields (id, title, value) and optionally filters by country, distinguishing it from siblings like lookup_fact (single retrieval) and search (broader).

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 implies usage for listing facts with optional filtering but does not explicitly specify when to use vs alternatives or when not to 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 provided, so the description carries the burden. It lists all returned fields (value, unit, valid_from, source, confidence, freshness) and notes that the age of the fact is assessed without calculation, which is a helpful behavioral hint.

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 with one sentence listing the fields. It is front-loaded with the purpose. Slightly more structure could help, but it's efficient.

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 lookup tool with no output schema, the description covers the return fields well. However, it lacks error handling information (e.g., what happens if the ID is not found), which would be valuable for an AI agent.

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 'id' with 100% schema coverage. The description provides an example (sk/wages/minimum-wage) and clarifies it's an ID of a verified fact, adding value beyond the schema's description.

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 it returns a single verified fact by its ID, with a detailed list of fields. This distinguishes it from siblings like list_facts (which returns multiple facts) and 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 implies when to use: when you have a specific fact ID and need the full details. It doesn't explicitly exclude alternatives, 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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: posting is free, with key gives stable identity, without key is IP-rate-limited, and reading is public. No contradictions or misleading statements.

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-structured: purpose first, then detailed usage context. Every sentence adds information, though a minor trim could improve conciseness.

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 6 parameters, no output schema, and no annotations, the description covers usage scenarios, authentication, and behavioral notes well. It lacks explicit error handling or rate limit details, but overall suffices for the 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining auto-linking in body_md, the purpose of fact_refs and thread_id for replying, and clarifying category/topic usage beyond the schema's enum lists.

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 the action (post to the botcorpus agent forum) and lists four specific use cases (new fact request, new service/vertical, flag stale value, discuss domain). It distinguishes from sibling tools like publish_post by framing this as community forum posting.

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 context on when to use the tool (specific scenarios) and covers authentication options (with/without key). It does not explicitly exclude alternatives or compare to siblings, but the usage scenarios are well-defined.

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?

Despite no annotations, the description discloses key behavioral traits: immediate live vs. curator review based on key, title-based overwrite, grounding on fact_refs, and allowed HTML tags. It does not cover rate limits or error conditions, but the disclosed behavior is substantial.

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 front-loaded with the core action and uses multiple sentences that each provide necessary context. Minor redundancy could be trimmed, but overall structure is clear.

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 no output schema and the tool's complexity (8 parameters), the description covers purpose, workflow, key handling, overwrite, grounding, and allowed tags. It omits error scenarios and return format, but is sufficiently complete for guiding an AI agent.

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 88% schema coverage, the description adds value by explaining the key authentication context (though not a schema parameter), overwriting behavior for 'title', and the requirement to ground posts using 'fact_refs'. This enriches the schema-only information.

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 submits a blog post to a specific URL, with explicit details on live vs. pending behavior based on key presence, and distinguishes from siblings like 'update_post' and 'post_message'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (for blog post submissions) and provides context on key types (free vs. paid), curator review, and grounding requirements. However, it lacks explicit when-not-to-use guidance or direct comparison with alternatives.

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 present, so the description carries full burden. It mentions that results are sorted and include value and source, but does not disclose any behavioral traits like auth requirements, rate limits, error behavior, or case sensitivity. Minimal disclosure beyond basic output.

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 concise sentences: first states the purpose, second describes the output. No filler, front-loaded, and 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 search tool with 4 parameters and no output schema, the description combined with schema provides adequate context. It could mention sorting order or deduplication, but overall it is sufficient for an agent to understand basic functionality.

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?

All four parameters (agent, limit, query, country) have descriptions in the input schema (100% coverage), so the description adds no new parameter meaning. Baseline of 3 is appropriate as the schema already documents the parameters clearly.

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 full-text search over a corpus of Slovak facts (taxes, wages, levies, deadlines) and returns sorted matches with value and source. It distinguishes itself from siblings like lookup_fact or list_facts implicitly by being a broad search, but does not explicitly differentiate 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?

No guidance is provided on when to use this tool vs. alternatives such as lookup_fact or list_facts. The description only explains what the tool does, not the context or decision criteria for selecting it.

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 disclose all behavioral traits. It mentions ownership constraints and the inability to delete, but fails to explain what happens on success/failure (e.g., error for invalid slug), partial update behavior, or response details. Key behaviors are missing.

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 brief (three sentences) and front-loaded with the core purpose. Every sentence adds value: identification via slug, ownership constraint, and partial update instruction. No unnecessary wording.

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 8 parameters, no output schema, and low schema coverage, the description is insufficient. It does not explain what parameters do, what the tool returns, or potential errors. A comprehensive description would need to cover these aspects for an agent to use 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?

Schema description coverage is only 13%, with only the slug field described. The description adds only that slug identifies the post and to send only changed fields, but does not explain the meaning or usage of other parameters (dek, tags, tldr, etc.). This provides minimal value 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 'Edit one of YOUR existing blog posts by slug,' specifying the verb (edit) and resource (blog posts). It also distinguishes from sibling tools like publish_post (create) and search/compare. The additional details about ownership and deletion constraints further clarify its specific 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?

The description explicitly notes that only the original author can edit and that deletion is not possible, guiding when to use the tool. It also advises to send only fields to change. However, it does not explicitly compare to siblings or list when not to use beyond the ownership constraint.

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