get_text

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

The description discloses far more than the readOnlyHint annotation: it details pagination, hidden-content handling (stripped/counted vs. included via include_hidden), labeling with origin, shadow-root behavior (open read, closed counted), and iframe handling with per-frame headers. It explains design rationale (display:none as injection channel), making the tool's behavior fully predictable. 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?

The description is a single dense paragraph, but every sentence adds value: it front-loads the core purpose, then expands on hidden content, shadow roots, and iframes. It is longer than typical, but the complexity of the tool justifies the length. No filler or repetition, so it is efficient despite its size.

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?

With 5 parameters, no output schema, and only readOnlyHint annotation, the description covers all critical behavior: pagination, hidden content, shadow roots, iframes, and origin labeling. It explains the output format conceptually ('labeled data with origin stated'), which is sufficient for an agent to know what to expect. Nothing essential is missing for safe and 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 0%, so the description carries the entire burden. It explains start_index (paginated), include_hidden (explicitly described), and location ('one region of it'). It implies max_chars via 'bounded pieces' but does not name it, and page is obvious from context. It adds substantial meaning to most parameters, though max_chars and page are not explicitly described—still a strong compensation.

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 ('Extract'), a clear resource ('readable prose from a page or one region of it'), and distinguishes itself by mentioning pagination and the origin-labeling of text. It differentiates from sibling get_page_view by specifying that it extracts prose and handles shadow roots/iframes in a defined manner, so an agent knows exactly what this tool is for.

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: it extracts readable prose, is paginated, and handles hidden content deliberately. It explicitly references get_page_view when comparing shadow-root behavior, implying when to use which, but does not state explicit exclusion criteria (e.g., 'use get_page_view for visual layout instead'). Still, it gives enough situational guidance for a competent agent.

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