sassy_http

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

With no annotations provided, the description carries the full burden. It transparently explains the safety gating for mutating verbs, including the adversarial LLM rationale and the protection against accidental destructive requests. It also gives concrete format examples for headers and body. It does not detail timeout behavior or error handling, but the key behavioral trait (mutating gate) is well disclosed.

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 front-loaded with the core action, then immediately contrasts with web_inspector. The parameter list is concise and scannable. The allow_mutating explanation is slightly long but directly serves safety and usage understanding. No redundant filler exists.

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 tool with an output schema and no annotations, the description covers purpose, usage guidance, parameter semantics for the key fields, and an important safety behavior. The only omissions are timeout_seconds and explicit return format guidance, but the output schema handles return values and timeout has a default. The description is sufficiently complete for an agent to invoke the tool correctly.

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 compensates by adding meaning to method (listing allowed values), headers (JSON example), body (string or JSON), and allow_mutating (required for state-changing verbs). It omits timeout_seconds and url, but url is self-explanatory and timeout_seconds has a default. Overall, it adds substantial semantic value beyond the 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 clearly states 'Make an HTTP request' as the core verb-resource pair and differentiates itself as a 'lightweight alternative to web_inspector for quick API calls.' This distinguishes it from sibling tools like web_inspector and sassy_http_ping, making the tool's purpose immediately obvious.

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?

'Lightweight alternative to web_inspector for quick API calls' provides clear usage context. Additionally, the explicit requirement that allow_mutating must be true for state-changing verbs guides when to use the tool (and what flag to set). It lacks explicit exclusions or alternative references beyond web_inspector, but context is strong.

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