Search value mappings

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

readOnlyHint=true is already in annotations, so the safety profile is covered. The description does add a useful behavioral qualifier — 'direct entity lookup by ID and version' — indicating a point lookup rather than an unfiltered scan. But it says nothing about behavior when all parameters are omitted (all three are optional), authentication needs, or result shape, so the added context beyond annotations is thin.

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 a single front-loaded sentence with zero filler — verb, resource, and qualifier appear immediately. Every word carries meaning; the brevity problem is one of omission (name parameter), not of wasted phrasing.

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 search tool with three undocumented optional parameters and no output schema, one sentence is not enough. An agent cannot tell what an empty-parameter call returns, whether results are exact matches, whether pagination exists, or how get_value_mappings differs in behavior. The description is adequate only if the agent already knows the tool.

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 bears the full burden of explaining id, name, and version. It covers id and version but omits the name parameter entirely, and it does not clarify whether matching is exact or partial or what happens when multiple/all parameters are absent. Compensation is only partial.

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 specific verb ('search'), a resource ('value mappings'), and a qualifier ('direct entity lookup'), which distinguishes it from the broader get_* and search_* siblings in the list. However, it never explicitly contrasts itself with the adjacent get_value_mappings or search_message_mappings, leaving some differentiation to inference.

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?

No when-to-use guidance is offered. The parenthetical 'direct entity lookup' weakly implies that this tool is for point lookups, but the description never names get_value_mappings or search_message_mappings as alternatives nor states the condition that would select one over another. An agent has to guess when this tool fits.

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