Invoke LIVE OpenAPI

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered structurally. The description adds a genuinely useful behavioral trait those annotations do not convey: hard allowlist enforcement ('Rejects unknown paths — does not invent APIs'), which tells the agent calls will fail fast rather than silently hit arbitrary endpoints. It still says nothing about auth requirements or the side effects of specific methods, so it stops short of a 5.

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?

Three dense sentences, front-loaded with the product scope and immediately followed by the allowlist constraint. Slightly jargon-heavy ('36 ops from live-2.0.json') but every sentence carries information and there is no filler.

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?

This is a destructive, open-world, 4-parameter tool spanning an entire product surface with no output schema and near-zero parameter documentation. The description covers scope and the allowlist guardrail but omits how to discover valid paths, what body/query shapes are expected, and what a successful or rejected invocation returns — significant gaps for a tool this broad.

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?

Only 1 of 4 parameters (25% schema coverage) has any schema description, and the description text adds nothing about method, query, or body semantics. For a 4-param open-world passthrough where three parameters are effectively undocumented, the description needed to compensate and does not; 'fill path params' appears only in 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 names a concrete product surface (Arvan LIVE 2.0) and enumerates its domains (streams, watermarks, reports, metrics), which distinguishes it from the sibling passthrough tools (invoke_cdn_api, invoke_vod_api, invoke_vads_api, etc.) that target other products. It never states the action verb explicitly (that a raw HTTP request is executed against that surface), but the product-scoped noun phrase plus the '[OPENAPI]' tag and 'Allowlist: 36 ops from live-2.0.json' make the purpose identifiable.

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?

It gives an implicit usage boundary: only the 36 allowlisted ops are accepted and unknown paths are rejected, so the agent knows it must be inside that set. However, it never says when to prefer this generic escape hatch over the dedicated siblings that already cover the same product (list_live_streams, get_live_stream, get_live_domain, list_live_watermarks), which is exactly the routing decision an agent needs.

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