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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral detail by clarifying this is a sitemap/URL-path search and that the result is scored URLs, not page content. There is no contradiction 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?

Two concise sentences front-load the core scope and return value with no filler. Every word contributes to understanding what the tool does.

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 definition is complete for a low-complexity, read-only search tool: it covers the domain, the matching mechanism, and the result shape. A note about limit behavior or scoring details could make it better, but the schema and annotations already carry part of that load.

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 has zero parameter descriptions, so the description needs to compensate. It does explain that query terms match against URL paths, which is valuable. However, the limit parameter is left entirely to its schema type, default, and bounds, leaving a small semantic gap.

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 action: 'Find pages on operator.blacklabelbots.com by words in their URL path (sitemap search)' and names the return type ('URLs with a match score'). It is clear and unambiguous, but it does not explicitly differentiate itself from siblings like read_page or site_info, so it falls short of a 5.

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 clearly establishes the tool's context: sitemap-based URL discovery by path-word matching. It gives enough information for an agent to select it for search tasks, but it does not explicitly state when not to use it or name alternative tools.

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