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

Beyond annotations, the description reveals the paid nature (2000 micro-dollar credits), the need for existing credits and a private Authorization header, and the billing impact of generating a new requestId. This is non-obvious operational context that annotations alone do not provide, and it is consistent with the idempotentHint.

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 tight sentences deliver the core action, cost, prerequisite, auth requirement, and recovery semantics with no filler. Critical constraints are front-loaded before secondary details.

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 paid external fetch tool, the description covers cost, prerequisite, authorization, recovery, and idempotent behavior. The output schema handles return-value documentation, so nothing essential is missing for an agent to call 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 schema covers requestId and maxPrice with meaningful descriptions, but the tool description adds the 'approved public HTTPS host' constraint relevant to the url input and clarifies that reusing requestId matters for billing. It does not deeply describe the input object, but that structure is visible in 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 names a specific operation: fetching readable text from an approved public HTTPS host. It is concrete and action-oriented, and the 'approved host' and 'readable text' focus helps set it apart from web/HTML siblings, though it does not explicitly contrast itself with alternatives.

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 explicitly instructs to first use agent_utilities_prepare and to reuse prepared arguments for recovery, giving a clear prerequisite and recovery workflow. It also states that a new requestId is a new billable operation, but it does not discuss when to prefer this tool over sibling extraction tools.

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