page_forms

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

No annotations are provided, so the description carries the full burden. The description does disclose the two main behaviors: what gets returned (form details + loose search boxes) and the GET-form simplification. However, it doesn't disclose edge cases like pages with no forms, JavaScript-rendered forms, or handling of malformed HTML, leaving some behavioral ambiguity.

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 two paragraphs and is front-loaded with the core purpose. Every sentence earns its place — the first paragraph defines the tool and its role, the second gives a practical alternative. Slightly verbose in the field enumeration but no wasted sentences.

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 read-only inspection tool with no output schema and no annotations, the description is fairly complete: it lists what fields are returned, its relationship to submit_form, and a pragmatic GET-form simplification. It could be more complete about the 'private' parameter, but overall it covers the key usage scenarios well.

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 coverage is 0%, so the description must compensate for the two params (url, private). The description describes 'on a page' referencing the url parameter contextually, but it doesn't explicitly document what each parameter means or how 'private' alters behavior. For a 2-param tool, this is a modest gap rather than a severe one.

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 has a specific verb+resource ('List the fillable forms on a page') and clearly enumerates exactly what's returned: method, action, submit-button label, fields (name, type, placeholder, label, select options), plus loose search boxes. It clearly distinguishes from sibling fetch_page and submit_form by stating this is the 'OBSERVE step before submit_form'.

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?

Excellent when-to-use guidance. It explicitly states this is the OBSERVE step to call before submit_form to learn field names. It also provides a clear when-NOT-to-use alternative: for GET forms, fetch_page with a query in the URL is simpler. This directly differentiates from sibling fetch_page and submit_form.

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