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

Annotations are not provided, so the description must carry the burden. It does disclose a meaningful behavioral detail: 'Query and fragment are dropped.' But it does not disclose any side effects (e.g., whether it makes network requests, caches results, or only performs local string parsing), and it states several parameters are 'discarded' without explaining why they exist or what triggers their use. This creates ambiguity about the tool's actual behavior.

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 main description is concise and front-loaded with the key outcome ('Return origin, host, and path'), and the second sentence adds a critical behavioral constraint. It is appropriately short. However, the parameter descriptions are verbose and introduce confusing extra concepts (weather hint, RSS titles, JSON validation) without clear connection, which detracts from overall structural clarity.

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 tool has no annotations and no output schema, so the description must be self-sufficient. For a tool that presumably validates or normalizes URLs, the description is missing essential context such as what the output format is, whether the tool performs network access, and how the six unrelated parameters interact with the normalization. An agent could easily mis-call this tool because the description does not explain why 'city', 'feed', 'json', and 'host' are needed for URL normalization.

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?

The schema descriptions cover each parameter literally, but the connection between the parameters and the tool's main purpose is unclear. Only 'url' directly relates to 'normalize-url'; 'ref', 'city', 'feed', 'host', 'json', and 'path' appear to be context parameters discarded after use, but the description does not explain this design. The phrase 'discarded after the shape check' for 'ref' and 'discarded after the call' for 'city' and 'json' adds some meaning but does not clarify how or why these are inputs to normalize-url.

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 ('Return'), resource ('URL'), and the output scope ('origin, host, and path'), plus a key behavior ('Query and fragment are dropped'). This makes the tool's main function clear. However, the description does not explicitly distinguish it from siblings like browser-url-ok or web-fetch, and the schema contains many unrelated parameters (city, json, feed) that muddy the purpose.

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 provides no explicit when-to-use guidance, alternatives, or exclusions relative to sibling tools. The list of sibling tools includes several URL-related tools (browser-url-ok, web-fetch, playwright-url-ok), but the description does not explain why normalize-url should be chosen over them. The parameter descriptions hint at validation scenarios, but no usage context is stated.

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