WebFetchSections

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

The description adds substantial behavioral context beyond the readOnlyHint, such as being a 'cheap structural preview' that 'avoids pulling the page body', resolving URL fragments, and returning a comment tree with metadata for Reddit. This enriches the agent's understanding of what the tool does and what it returns, though it does not cover every edge case.

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 well-structured with a clear opening sentence, detailed usage guidance, and a separate Reddit note. It is slightly longer than necessary but every sentence contributes value, and the main purpose is 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?

The description is largely complete for a tool with two parameters and no output schema. It covers purpose, typical usage, URL fragment handling, and Reddit-specific behavior. However, the unexplained 'slice' parameter leaves a notable gap in contextual completeness.

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 0% description coverage, and the description does not explain the 'slice' parameter at all. The only mention of 'slices' refers to the follow-up tool web_fetch_incisive, not this tool's slice parameter. The description fails to compensate for the missing schema descriptions, leaving the agent without guidance on how to use 'slice'.

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 opens with 'List a document's section headings to understand page composition or plan targeted extraction,' providing a specific verb, resource, and intended use. It clearly distinguishes itself from web_fetch_incisive by positioning it as a preliminary structural preview.

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 states the workflow: 'call this first... then follow up with web_fetch_incisive using the returned heading names as section= or slugs as slices='. It also provides Reddit-specific guidance, making the when-to-use unambiguous.

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