get_mapping

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

It discloses important behavior beyond the readOnlyHint: the output is a flattened catalog showing field path -> type, includes multi-fields like .keyword, and optionally returns dynamic templates and total field count. It also clarifies the raw=true switch returns the untouched mapping JSON. This precisely sets expectations for what the agent will receive.

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?

It is only two sentences long and stays on task. The first sentence states the primary action and its main output; the second sentence adds the raw-mode option without fluff. Every phrase in the result provides value.

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?

The description covers the operational core: what the tool returns, why an agent would need it, and the raw toggle-and has an output schema to document returned values. It is almost complete, but the field_filter parameter is still a black box, and since the schema itself has no descriptions, an agent would not know how to use that particular optional input effectively.

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 is the only source of parameter meaning. It explains raw=true and implicitly clarifies that index names the mapping target, but it says absolutely nothing about field_filter. That parameter remains a mystery, which is a meaningful gap because an agent may incorrectly spread or omit it. The description adds some value but does not fully compensate for the missing schema 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 opens with a specific verb and resource: 'Get the mapping for an index,' and immediately distinguishes the tool from write-oriented siblings like put_mapping. It also clearly explains the output's purpose, which makes the tool's role among the sibling list unambiguous.

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 gives a concrete use case: 'which is what you need to write correct queries,' meaning the tool should be run when the agent needs field-level type information to construct valid queries. It does not explicitly name alternatives or when-not-to-use scenarios, but it offers enough contextual direction to route an agent correctly.

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