zerodom_parse_url

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

With no annotations provided, the description carries full behavioral burden. It discloses the compact text output format, that CSS selectors are kept server-side (saving context), the cost of enabling frames (a read per frame), and the default off behavior. This is substantive and honest about trade-offs, though it does not mention error handling or side effects on browser state.

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 paragraphs, each earning its place. The first sentence states purpose and return format, then the selector behavior, then a paragraph on frames with rationale. It is front-loaded and efficient, though the frames paragraph could be tightened slightly. No fluff.

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?

Given an output schema exists, the description need not detail return structure, but it still provides the compact graph format and mentions the verbose option. It covers the key flags, costs, and use case for frames. The only missing piece is explicit mention of error conditions or whether navigation is stateful, but for a navigation tool this is adequate.

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 must compensate entirely. It explicitly explains frames ('Set frames=True when the controls you need are inside an iframe') and verbose ('pass verbose=True for the full JSON'), and url is self-evident from the purpose. Every parameter is given meaning beyond the bare 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 opens with a precise verb-resource pair: 'Navigate to a URL and return its interaction graph.' This clearly distinguishes the tool from siblings like zerodom_read_page (which presumably reads the page text) and zerodom_click_node (which acts on nodes). No ambiguity about what it does.

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 detailed parameter-level guidance (when to set frames=True, when to use verbose=True) but never contrasts this tool with its siblings. It does not say 'use this instead of read_page when you need the graph' or state exclusions. Usage context is implied by the purpose but not made explicit, so an agent might still hesitate between parse_url and read_page for navigation tasks.

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