url_metadata

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

With no annotations, the description discloses critical safety behaviors: SSRF protection against private/loopback/link-local/cloud-metadata, redirect re-validation, and a 2MB body cap. It also enumerates the full set of return fields, giving the agent a clear picture of the response shape. It does not mention error handling or rate limits, but the core behavioral traits are covered.

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, information-dense sentence plus a second sentence on safety. No filler or repetition; every phrase adds a behavioral or output detail.

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 enumerates the exact metadata fields returned, making the tool's output predictable without an output schema. It also covers safety, redirect handling, and size limits. Given four parameters and no output schema, this is ample context.

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 covers half of parameters with descriptions (url, user_agent); description adds constraints beyond schema by specifying 'public HTTPS URL' and 'SSRF-protected' for url, and 're-validates every redirect' for follow_redirects. However, timeout is entirely undocumented in both schema and description, leaving its meaning to the parameter type/constraints.

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 specific verb ('Fetch') and a concrete resource ('public HTTPS URL'), followed by an extensive list of extracted metadata. This unambiguously differentiates it from sibling utilities like dns_lookup or sitemap_extract.

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?

While no explicit alternatives or exclusions are named, the tool's scope is clear: it is for URL metadata extraction. The SSRF constraints and 2MB cap implicitly define when not to use it (non-public/internal URLs, very large pages), though no sibling comparison is provided.

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