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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds useful behavior beyond that — default case-insensitive substring matching, JS regex semantics, and what a 'descriptions' match returns — but says nothing about result limits, pagination, or ordering, which matter for a potentially broad cross-configuration search.

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 definition is front-loaded with purpose and question examples, then moves through parameters in a logical order with no filler sentences. It is on the longer side for seven parameters, but nearly every clause carries actionable information.

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 seven-parameter read-only search with no output schema, the description covers scoping, matching mode, and regex behavior well. The remaining gap is that the shape and volume of results are never described, so an agent cannot anticipate truncation or pagination on broad searches across all configurations.

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 100%, so the baseline is 3; the description earns an extra point by explaining the intent behind parameters rather than restating them, particularly the 'descriptions' target (matching documentation text and returning the description) and the rationale for omitting configurationId. It adds meaning about matching semantics that the schema only briefly touches.

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 first sentence gives a specific verb and resource ('Search for keys or values inside one or all configurations') and immediately narrows the scope to the current project. The concrete question examples ('where is maxPlayers set?') make it unambiguous that this is a search tool rather than the get/list siblings such as get_configuration or list_configurations.

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 rules are given for every mode: omit configurationId to fan out across all configurations, set isRegex for regex queries, and use target to switch between keys, values, both, or descriptions. The 'descriptions' guidance even names the scenario (finding a key when you don't know its name), so an agent can pick the right invocation without inference.

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