poll_url

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

With no annotations, the description carries the full behavioral burden. It discloses the polling loop, stop conditions (status or body pattern), defaults for timeout and interval, and header format. It does not state what happens when the timeout expires or on network errors, which is a notable gap, but the core retry behavior is clearly described.

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 organized with a one-sentence summary, use cases, illustrative examples, and a compact argument list. Every section adds functional value—examples make the polling semantics concrete, and the Args block mirrors the schema without padding.

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 the output schema exists, return values need not be explained. All input parameters and their interactions are covered, plus examples. The main omission is failure/timeout behavior, which matters for a polling tool, but overall the definition provides enough context for correct invocation in typical deployment and health-check workflows.

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 is solely responsible for parameter meaning. It documents all seven parameters with practical details, including the regex semantics for expected_body_pattern, the exact header format, and the min/max/default values for timing parameters. This exceeds what the bare schema provides.

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 precise action: 'Poll a URL repeatedly until it returns expected status/content.' This clearly identifies the resource (URL), the operation (polling), and the completion condition, distinguishing it from the unrelated memory and monitoring siblings.

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 names concrete use cases ('waiting on deployments, health checks, APIs') which tells an agent when to apply the tool. It does not explicitly discuss when not to use it or mention alternatives like monitor_command or watch_file, but the scenarios are clear enough for selection.

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