medusa_admin_request

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that POST/DELETE are destructive and instructs the user to confirm first, and notes the path must start with /admin. However, it doesn't disclose auth requirements, rate limits, response format, or what happens on errors. It's an escape hatch—inherently higher-risk—but the description does flag the key risk (destructive actions).

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 compact at two sentences, front-loads the core purpose ('low-level escape hatch'), and packs the key constraints (path must start with /admin, destructive confirmation). Every sentence earns its place. Could add a tiny concrete example, but overall is efficient and well-structured.

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?

Given this is a general-purpose HTTP passthrough with no output schema and no annotations, the description does a reasonable job covering the essential guidance: what it does, when to use it, key constraints, and safety warnings. It doesn't over-specify return values (reasonable for an unspecified endpoint), but is adequately complete for an escape-hatch tool. The naming of uncovered domains helps the agent route 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 coverage is 75%, so most parameters are already documented in the schema. The description adds the constraint that path must start with /admin, which is useful context beyond the schema's example. However, it doesn't explain the interaction between body/query and method semantics (e.g., which methods typically take a body), nor provide examples of how to combine the parameters.

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 it's a low-level escape hatch to call any Medusa Admin API endpoint directly, with specific verb (call) and resource (Medusa Admin API). It explicitly lists uncovered use cases (fulfillments, price lists, promotions, refunds, uploads), distinguishing it from the curated sibling tools. Slightly weaker on naming exactly what it returns.

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 explicitly says 'Use for anything the curated tools don't cover' and lists examples of uncovered domains, which signals when this should be used vs sibling curated tools. It also warns about POST/DELETE being destructive and says to confirm with the user first. However, it doesn't explicitly name alternative tools for covered use cases or state 'don't use this if a curated tool exists' as explicit exclusion guidance.

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