ms_get_raw

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful context beyond these: the specific safe-verb restriction, the host-override default behavior, the return envelope shape ('{"ok": true, "status", "data"}'), and the note that some read APIs accept a body. The error envelope is mentioned but not detailed, keeping this just 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?

The description is front-loaded with the core purpose, followed by the API reference link, verb constraints, sibling routing, a clean Args block, and the return format. Every sentence earns its place; 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?

For a raw passthrough tool with 5 parameters and 0% schema coverage, the description covers purpose, target API, verb constraints, parameter semantics, defaults, examples, alternatives, and return format. An output schema exists, so return values need not be elaborated further. Nothing an agent needs to invoke this 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 description coverage is 0%, so the description carries the full burden of parameter documentation. It documents all 5 parameters with actionable detail: path format with a concrete example prefix, method default, host override semantics, query-string purpose, and body usage note. This fully compensates for the schema's lack of descriptions.

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 states a specific verb and scope: 'Read ANY endpoint by path, including ones missing from the catalog.' It clearly identifies the resource (raw API endpoints by path) and is immediately distinguishable from sibling tools because it names the write and delete alternatives it is not.

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?

Explicit routing guidance is provided: 'Safe verbs only (GET, HEAD, OPTIONS). To change data use ms_write_raw, to delete use ms_delete_raw.' This tells the agent exactly when to use this tool versus its siblings, leaving nothing to inference.

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