BlockRazor Docs

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

Annotations already cover read-only and open-world hints. Description adds that answers are synthesized with source links and can be tailored via 'goal' parameter, but doesn't detail other behavioral traits like latency or 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?

Two efficient sentences: first states core functionality, second gives usage guidance. No unnecessary words, well front-loaded.

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 two parameters and no output schema, the description adequately explains the return format (synthesized answer with links) and the role of the optional 'goal' parameter. Missing details on edge cases but still complete for typical 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 already describes both parameters well (100% coverage). Description adds context that 'goal' tailors the answer, which goes beyond the schema 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?

Clear verb ('ask'), resource ('BlockRazor'), and outcome ('synthesized answer with links'). Explicitly distinguishes from sibling 'searchDocumentation'.

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?

States when to prefer this tool (direct answers) versus alternatives ('searchDocumentation'/'getPage' for browsing). Provides clear guidance on usage context.

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, destructiveHint, idempotentHint, and openWorldHint. Description adds that it fetches markdown content, accepts full URLs, and includes navigable links. No contradictions. Adds useful behavioral context 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?

Three sentences: front-loaded with purpose, then usage and input format, then sibling contrast and navigation feature. No redundant 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 low complexity (1 param, good schema, annotations), description sufficiently explains what it returns, when to use it, and how it relates to siblings. No missing critical information.

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 for url parameter is present (100% coverage). Description adds example URL format and clarifies it accepts full URLs, adding meaning beyond 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?

Description clearly states verb (Fetch), resource (full markdown content of a specific documentation page), and context (BlockRazor). It distinguishes from sibling searchDocumentation by mentioning partial vs. full content.

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?

Explicitly says 'Use this when you have a page URL and want to read its content.' Also contrasts with searchDocumentation: 'use getPage to retrieve the complete page when you need more details.' Provides clear when-to-use and alternative.

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, open-world, and idempotent. The description adds that the search returns contextual content with titles and direct links, giving the agent insight into the response format. 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?

Three concise sentences, front-loaded with the action, followed by usage guidance, then output description. No unnecessary words; each 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?

Given only one parameter and no output schema, the description adequately covers the return type (titles and links) and the scope (BlockRazor documentation). Could mention limitations like result count, but overall sufficient.

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 only parameter 'query' is a string with no description in the schema (0% coverage). The description adds no additional meaning about the query parameter, such as format or expected input. With low schema coverage, the description should compensate but does not.

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 searches documentation for various content types (code examples, API references, guides). It specifies the resource (documentation) and action (search). While it distinguishes itself from siblings by being a search tool, it does not explicitly contrast with siblings like askQuestion or getPage.

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 lists when to use: to answer questions about BlockRazor, find specific documentation, understand features, or locate implementation details. It provides clear context for use but does not mention when not to use or suggest 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with a non-destructive write operation. The description adds context about the tool's purpose (reporting to a team) and constraints (one issue per call, no duplicates), which goes beyond annotations. However, it does not detail the internal behavior (e.g., how feedback is stored or who receives it), but that is acceptable for a simple feedback 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 moderately concise (four sentences) and well-structured: first sentence states purpose, second lists usage conditions, third gives a sanity check rule, and fourth provides usage constraints. Every sentence adds value without redundancy. Slightly longer than necessary but still effective.

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 simplicity (3 parameters, no output schema, no nested objects), the description covers all necessary aspects: when to use, what to include in content, how to handle observations vs. user reports, and constraints. An agent can reliably decide to invoke this tool and format the call correctly based on the description alone.

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%: all three parameters have descriptions. The tool description reinforces the 'content' parameter with additional guidance (quote exact sentence, no personal info), but adds minimal new meaning beyond the schema. Baseline is 3, and the description does not significantly elaborate on parameters beyond what is already in the input 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 states the tool is for reporting documentation issues in BlockRazor. It uses a specific verb ('Report an issue') and resource ('documentation of BlockRazor'), and distinguishes from sibling tools (askQuestion, getPage, searchDocumentation) by specifying it is only for reporting problems, not for asking questions or 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 provides explicit when-to-use conditions: when encountering outdated, contradictory, or missing info, or when the user reports a problem. It also gives when-not-to-use (do not use to confirm accuracy), and includes guidelines like one call per issue, not reporting same issue twice, and a sanity check before reporting.

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