kde_window_find

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's incremental contribution is the cardinality contract ('exactly one window') and the ambiguity branch returning candidates — genuinely useful behavior an agent cannot infer from structured fields. It omits what happens if both title and app_id are null and says nothing about ordering or result limits.

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?

A single compact sentence with the cardinality constraint front-loaded and the ambiguity behavior appended. No filler, nothing redundant with the schema.

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?

No output schema exists, and the description does hint at the return shape via 'ambiguity returns candidates', which helps. However, the required 'session' parameter — including the security-sensitive 'user-desktop' opt-in — goes unmentioned, and the no-match case is undefined, leaving meaningful gaps for a lookup 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 only 33%: 'session' is documented in the schema, but title and app_id are bare. The description partially compensates by clarifying that title is a substring match (not exact) and that the two filters combine with 'and/or', but it does not explain the matching semantics of app_id or the behavior of the required session selector.

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 and resource ('Find exactly one window') plus the matching criteria (app ID and/or title substring). This clearly distinguishes it from kde_window_list (enumerate) and kde_window_inspect (examine a known window), though it never names those 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?

Implies when to reach for it: when you want a single window narrowed by app ID or title text. It also signals the fallback outcome when the query is ambiguous (returns candidates), but gives no explicit guidance on when to prefer kde_window_list instead or how to resolve the candidate list.

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