hibot

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

Adds the behavioral detail that it reads the website to infer the brand and describes the fallback when reading fails. Annotations declare non-destructive; description does not claim read-only, so no contradiction. Extra context about site reading is valuable beyond 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?

Two sentences with no filler, front-loaded with the core purpose and key details. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, output mapping to ANSWER categories, and fallback behavior. Return format is implicit but clear from 'Generate questions'. Slightly light on what the exact output looks like, but acceptable given no output 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?

Schema already documents all parameters (100% coverage). Description adds meaning by explaining when brandName and description are needed (when the site cannot be read), going 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?

Clearly states the tool generates AI-visibility questions for any brand from its website, with a specific verb and resource. It maps to six ANSWER categories, distinguishing it from sibling content-retrieval tools.

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?

Mentions usefulness for AEO/GEO research and content planning, providing clear context. It does not explicitly exclude alternatives or name sibling tools, but the generative nature is distinct enough.

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, destructiveHint=false, and openWorldHint=false, so the tool is safe and static. The description adds context about the content type (framework explanation) and its role in clarifying scores. It doesn't contradict annotations and provides useful detail beyond the structured data.

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 long, with the primary purpose front-loaded and a concise list of contents. Every phrase earns its place, and there is no filler or redundant information. It reads efficiently and gives the agent exactly what it needs to understand the tool's function.

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 parameterless, read-only documentation tool with no output schema, the description is fully adequate. It states what the tool provides (the framework components) and its intended use (explaining scores). No additional information is needed for an agent to decide to invoke this 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 tool has zero parameters, and the schema coverage is 100% (empty). Per the rubric, a baseline of 4 is appropriate when there are no parameters, since the description doesn't need to clarify parameter meaning. The description doesn't add parameter-specific information because there is none to add.

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: 'The ANSWER framework for measuring AI visibility' and enumerates its components (six categories, rubric, weights, score bands, letter-grade scale). It distinguishes itself from siblings like generate_ai_visibility_questions and get_blog_article by focusing on methodology explanation rather than content retrieval or question generation.

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

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

The description includes an explicit usage directive: 'Use it to explain what an AI visibility score means and how each category is defined.' While it doesn't name alternative tools, the context of siblings makes the appropriate use clear. It could be more explicit about when not to use it (e.g., not for generating questions or fetching articles), but the purpose is 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 and destructiveHint, so the description correctly adds value by specifying the output format (readable Markdown) and inclusion of the canonical URL. It also notes the content is reference reading, giving context on its nature. This goes beyond what annotations provide.

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, well-structured sentence that front-loads the core purpose and immediately states the output format and URL inclusion. No wasted 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?

For a simple read-only tool with one parameter and no output schema, the description is nearly complete. It tells the agent what the result looks like (Markdown with canonical URL) and what the content covers. It does not mention error behavior for invalid slugs, but that is minor for a read operation.

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 fully documents the slug parameter (100% coverage), so the description does not need to add much. The description mentions 'by slug' but adds no extra detail about the parameter's format or source. It meets the baseline for high schema 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?

The description clearly states it retrieves one published HiBot article by slug and renders it as Markdown with its canonical URL. It also specifies the content focus (AI visibility and ANSWER framework). This distinguishes it from sibling tools like list_blog_articles (listing) and search_blog (searching).

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 when a specific slug is known and a single article is needed. It does not explicitly name alternatives or exclusion conditions, but the purpose is clear enough that an agent can infer the correct context. The schema hint about slug sourcing from list_blog_articles or search_blog is not in the description, but the description itself 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: it lists only 'Published' articles and orders them 'newest first', which goes beyond the annotations. It does not mention pagination details, but those are captured in the schema, so the description adds solid value without 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?

Two short sentences with no filler. The core action and scope are front-loaded in the first sentence, and the second sentence provides a concise usage hint. Every word earns 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?

For a read-only list tool with fully documented parameters and a read-only annotation, the description covers the key behavioral points: published status, ordering, and filterability. It does not describe the return shape, but given the straightforward nature of a list operation and no output schema, this is acceptable and complete enough 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?

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The description's phrasing 'optionally filtered to one ANSWER category' essentially restates the category parameter's schema description. It adds no new parameter-level meaning, so it sits at 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 states a specific verb (list), resource (blog articles), and domain scope (AI visibility and ANSWER framework). It also provides ordering (newest first) and a filter option, clearly differentiating it from siblings like search_blog and get_blog_article without needing to inspect 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?

The trailing 'Reference reading' hints at a use case but does not explicitly state when to use this tool versus alternatives like search_blog or get_blog_article. There are no exclusions or explicit alternative routing, so usage guidance is implied rather than definitive.

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 readOnlyHint=true and destructiveHint=false. The description adds useful behavioral detail beyond those: results are relevance-ranked and include page URLs, and only published articles are searched. This is enough for a safe, read-only search 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?

Two sentences with no filler. The core behavior is front-loaded in the first sentence, and the second sentence adds useful topical context about AI visibility and the ANSWER framework.

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 search tool, the description is nearly complete: it names the resource, the operation, the ranking behavior, and the output detail that matters most (page URL). With no output schema present, it could have specified return format more explicitly, but it gives enough for an agent to select and invoke 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 100% and both parameters are already well documented ('Keywords to search for', 'Results to return. Default 10.'). The description adds no extra parameter-level meaning, so the baseline of 3 applies.

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 ('keyword search') and resource ('published HiBot articles'), and adds distinctive behavioral details: relevance ranking and per-result page URLs. This clearly separates it from siblings like list_blog_articles and get_blog_article.

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 gives clear context: this is for keyword-based searching across published articles and serves as reference reading. It does not explicitly name alternatives or say when not to use it, so it stops short of a 5, but the intended use is unambiguous.

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