Search preference names

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

Annotations declare readOnlyHint=true, so the safety profile is already covered; the description adds real context beyond that by disclosing that values are truncated and that results are name-only matches with current/user-set status. This warns the agent not to treat output as a full value dump. The truncation length itself is unspecified, which is a minor gap.

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 tight sentences: what is searched, what is returned and why, then the truncation caveat. Every sentence carries information and the core action is front-loaded.

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 does the work of explaining the return shape (names + values + user-value flag) and flags truncation, which is sufficient for correct invocation. Ordering and exact truncation behavior are left unstated, a small residual gap for a simple read 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 coverage is 100%, so both 'query' (substring match, with example) and 'limit' (1-200, default 40) are already fully documented. The description adds the concept of a substring match consistent with the schema but nothing about limit semantics, so baseline 3 applies.

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 (search) and resource (Firefox preference NAMES) plus the underlying API (Services.prefs.getChildList), and describes exactly what is reported back: matching names, current values, and whether a user value exists. This clearly separates it from browser_get_pref (single pref lookup) and browser_set_pref (mutation) among the many siblings.

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 an explicit use case and workflow: discover the pref behind a setting before changing it with browser_set_pref. It also implies an exclusion by calling itself a discovery tool rather than a dump. It does not explicitly mention browser_get_pref as the follow-up for a known exact name, so the routing is slightly incomplete but still clear.

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