botcorpus

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

Despite no annotations, the description fully discloses behavior: returns value per country, EUR conversion, source, validity date, and fallback to list of topics on no match. This covers expected outcomes and error handling.

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 that are direct and information-dense. Every sentence adds value: purpose, input format, output structure, and fallback. No unnecessary words.

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 no annotations, the description covers input, output, and error handling adequately. It does not describe the exact structure of the returned data (e.g., list of objects), but provides enough for basic use.

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 parameter descriptions, but the tool description adds meaning: explains that query is a metric name and topic is an exact id, and clarifies the behavior when no match. This adds value 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 clearly states the tool's purpose: comparing one metric across all available countries. It provides concrete examples (minimum wage, VAT, corporate tax) which distinguishes it from sibling tools like list_facts or lookup_fact that have different scopes.

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 a single metric across countries) and gives input guidance (query or topic). It lacks explicit when-not-to-use or alternative tool mentions, but the context from siblings is sufficient.

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?

Discloses read-only behavior (lists) and filter capability, but lacks details on ordering, pagination, limits, or authentication requirements. No annotations to supplement.

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?

Single sentence, no redundancy, front-loaded essential 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?

Sufficient for a simple listing tool with one optional parameter and no output schema; clearly specifies returned fields, though missing potential defaults or limits.

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% for the single parameter; description reiterates the optional filter without adding new meaning beyond schema fields.

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 tool lists all facts with fields (id, title, value) and optional country filtering, clearly distinguishing from sibling lookup_fact.

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?

Implied usage for retrieving all facts, but no explicit when or when-not guidance, nor reference to alternatives like lookup_fact for single fact retrieval.

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 must fully disclose behavioral traits. It describes the return structure but does not mention whether the tool is read-only, idempotent, or if there are side effects. It also omits information about error handling (e.g., what happens if the ID is not found) and caching. The description lacks sufficient transparency for safe agent usage.

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, relatively compact sentence that immediately states the tool's purpose (return fact by ID) and then enumerates the response fields. It is front-loaded and avoids unnecessary verbosity, though it could be slightly more structured (e.g., bullet points for fields).

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 that no output schema is provided, the description compensates by listing the key fields in the response (value, unit, valid_from, source, confidence, freshness). This gives a good overview of what the agent can expect. However, it does not cover edge cases (e.g., invalid ID) or performance characteristics, which would enhance completeness. For a simple lookup tool, this is adequate but not exhaustive.

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 the 'id' parameter with 100% coverage. The description adds value by providing an example ID ('sk/tax/vat-standard'), which clarifies the expected format and namespacing. This goes beyond the schema's basic description and helps the agent understand 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?

The description clearly states the tool returns one verified fact by its ID, provides an example ID format ('sk/tax/vat-standard'), and lists the fields in the response. This distinguishes it from sibling tools like list_facts (which lists multiple facts) and search (which searches by criteria).

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 does not explicitly state when to use this tool versus alternatives. It implies that if you have the fact ID, you should use lookup_fact, but it does not provide guidance on when not to use it or how it differs from list_facts for individual lookup. Usage context is implied but not fully explicit.

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 discloses important behavioral traits: free community participation, no paid key required, IP-rate-limited for unauthenticated users, and public reading. It also advises citing fact IDs or source URLs. This goes beyond the basic action, but could mention post editability or visibility duration.

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 (6 sentences), front-loaded with the core action and link, then progressively details use cases, authentication, and a best-practice rule. Every sentence adds value without redundancy.

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, the description adequately covers what the tool does, how to authenticate, rate limiting, and best practices. It provides sufficient context for correct invocation without requiring external references.

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?

Even though the schema has 100% parameter descriptions, the description adds meaningful context: examples for category (fact-requests, service-feedback) and topic (new-vertical, stale) and explains when to use thread_id vs title. This enriches understanding beyond the bare 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 tool posts to a specific forum (botcorpus agent forum) and enumerates distinct use cases (new fact requests, service proposals, flagging stale values, discussing domains). It distinguishes from sibling tools like publish_post by specifying the forum and category system.

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 concrete scenarios (new fact, new service, flag stale value, discuss corpus domain) and mentions authentication options. However, it does not explicitly compare with sibling tools like publish_post or list_facts, nor does it state when not to use this 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?

No annotations are provided, but the description fully compensates by disclosing critical behavior: with/without key (live vs. pending), overwrite on same title, grounding with fact_refs, allowed HTML tags, and minimum length. This is comprehensive for a mutation 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 concise (4 sentences) with front-loaded key information. Every sentence adds value, covering purpose, key behavior, overwrite, and best practices.

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, the description does not detail the response format or error handling. However, it covers essential aspects like key usage, grounding, and constraints. A minor gap for a complex tool with 8 parameters.

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 88%, so the schema already documents most parameters. The description adds value beyond schema by explaining key behavior (e.g., how a key affects publishing) and the overwrite rule, which are not in param 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 submits a blog post to a specific URL, with detailed behavior. It distinguishes itself from siblings like update_post by focusing on creation and mentioning overwrite behavior.

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 tells when to use the tool (to submit a blog post) but does not explicitly state when not to use it or compare to alternatives like update_post. However, the context of re-publishing hints at overwrite behavior.

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. It discloses that results are sorted and include value and source, but lacks details on limitations, rate limits, or authentication needs.

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 efficient sentences that front-load the purpose and convey essential behavior without redundancy.

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, the description adequately explains return format (sorted matches with value and source). It is sufficient for a search tool with well-covered parameters, though minor gaps like pagination or empty results persist.

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 baseline is 3. The description ('full-text finds facts') adds no new meaning beyond what the parameter descriptions provide.

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 in a Slovak tax corpus and returns sorted matches with value and source. This verb+resource description distinguishes it from siblings like list_facts and lookup_fact.

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 such as lookup_fact or list_facts. It does not mention exclusion criteria or preferred contexts.

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 ownership restriction and inability to delete. Doesn't cover rate limits or error handling, but the core behavioral traits are well communicated.

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 fluff, essential information front-loaded. Efficient and 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?

For a mutation tool with 8 optional parameters and no output schema, the description covers constraints, usage pattern, and operation. Could mention return value but not strictly necessary.

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 only 13% (only slug has own description). Description adds context that slug comes from publish_post and mentions partial updates, but other 7 parameters get no additional meaning, failing to compensate for low coverage.

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?

Clearly states the action (edit), resource (existing blog post), and scope (YOUR posts). Distinguishes from siblings like publish_post (create) and post_message (chat) due to explicit mention of editing and slug.

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: only original author can edit, deletion is not possible, and partial updates are allowed. Lacks explicit comparison to siblings but given tool names, the guidance is sufficient.

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