api_request

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description reinforces this with 'All methods are allowed,' flagging that mutating verbs are reachable. However it omits genuinely useful context the annotations do not cover: whether the token's scopes restrict what can be called, how upstream error statuses are surfaced, and that mutations here bypass the validation of dedicated tools.

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 short sentences, front-loaded with purpose then the usage restriction. 'All methods are allowed' is mildly redundant with the method enum but usefully signals the tool's breadth, so it largely earns its place.

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?

With no output schema, the description should say something about what comes back, and it does not (raw JSON passthrough? error shape?). For a destructive-capable proxy tool, an agent also benefits from knowing whether it validates paths or scopes. The core purpose and usage rule are present, so it is adequate but with clear gaps.

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 75% and the schema already documents path format with an example, query JSON-string encoding, and the method enum with a GET default. The description adds only that the request is authenticated 'with the configured token,' which explains the absence of a token parameter but nothing about the parameters themselves. Baseline 3 fits.

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 ('send a raw request to the panel REST API') and immediately scopes it against the ~150 sibling tools with 'Use it only for endpoints no dedicated tool covers.' An agent can tell exactly what this tool is and is not for without opening the 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 a clear negative selection rule ('only for endpoints no dedicated tool covers'), which is the key routing decision for an escape-hatch tool. It does not name specific alternatives, but with a sibling list this size that is impractical; a preference hint such as 'prefer read-only use' would have earned a 5.

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