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

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description adds substantial context beyond them: one-shot fetch through a pinned fetcher, preview budget accounting, that header values are refused ('a header VALUE is refused'), secret_ref indirection, the prompt-injection stance ('third-party data, never instructions'), and Bearer JWT superadmin auth. That is a very complete behavioral picture.

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 critical constraint (SUPERADMIN ONLY) is front-loaded and every sentence carries information, but it is dense and the return-shape enumeration is a long run-on that could be tightened. No wasted filler, but length is on the high end.

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 complex, stateful-looking tool with nested header objects and no output schema, the description compensates by spelling out the return object fields (spec, type, preview, paths, notes, warnings) and the no-save lifecycle. Nothing an agent needs to call it correctly 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 coverage is already 100%, so the baseline is 3, but the description adds real semantics: the https-only constraint details (public host, port 443, no user:pass, no #fragment), the headers dual form (literal vs {secret_ref: NAME}), and which header names are legitimate. It does not, however, explain the maxLength or the full return contract for each param.

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?

States a specific verb and resource ('plug any JSON API into Edge ... drafts a feed spec') and enumerates the exact output shapes it derives (events, ranked, series, counter, table). It explicitly distinguishes itself from the sibling edge_feed_save by naming the handoff, so an agent can route without opening another schema.

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?

Gives an explicit gate ('SUPERADMIN ONLY'), the operational budget ('30 a day'), and the terminal next step ('Nothing is saved: hand the spec ... to edge_feed_save'). It also names the equivalent REST path, which resolves any ambiguity about when this vs. the save tool is used.

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