url_encodeEncode text for safe use in URLs. Choose component mode to escape special characters for query values, or uri mode to preserve them.
Percent-encode text. component mode escapes & = ? / for use inside a query value; uri mode preserves them. Web version: https://buildutilities.com/url-codec
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | component | |
| text | Yes |
Changes observed during successful MCP inspections.
v0.1.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral detail by specifying which characters are escaped in component mode versus preserved in uri mode, which is valuable context beyond the annotations.
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 brief, with the primary purpose stated first, followed by the mode distinction, and a supplementary web link. Every sentence earns its place; no wasted words.
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 simple, side-effect-free encoding tool with no output schema and straightforward parameters, the description covers purpose, mode behavior, and the text input implicitly. The return value (encoded string) is obvious from the operation. Annotations cover the safety profile, and no critical information is missing.
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 carries the burden of explaining parameters. It explicitly describes the mode parameter's two values and their effects. The text parameter is self-explanatory from the phrase 'Percent-encode text', so the description effectively compensates for the missing schema descriptions.
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 clearly states the tool percent-encodes text, distinguishing it from siblings like base64_encode and url_decode. It also specifies two modes with concrete character-level behavior, leaving no ambiguity about what the tool 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 explains when to use each mode ('component mode escapes & = ? / for use inside a query value; uri mode preserves them'), providing clear guidance on mode selection. However, it does not mention alternatives or when not to use this tool versus other encoding/decoding siblings, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.