tc_find

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

With no annotations, the description carries the full burden and does well: it discloses that empty results are not errors (ok stays true), that timeout causes ok=False on wait, how retry/timeout semantics work, and what diagnostics accompany a miss (known-filter check, actually-present classes). It omits any note on side effects or rate limits, so a 4 rather than 5.

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?

Front-loads the purpose and the required-parameter convention, then organizes per-action stanzas. The repeated '(parameters as in ...)' cross-references and signature blocks add length, but most sentences carry real information rather than filler.

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 an 8-parameter tool with no annotations and no output schema, the description is thorough: it covers every action, field semantics, the connection requirement, and the reference-lifetime caveat ('pass reference values unchanged... find the element again'). The only gap is a slightly thin distinction between cls and type.

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 must compensate, and it largely does: it documents name/cls/type/root_ref/title/timeout/connection_id and explains wildcard support (* and ?), root_ref default (active window), and timeout semantics. A few fields (notably 'type' vs 'cls') are explained somewhat indirectly, leaving minor ambiguity.

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 ('Search the UI tree for objects') and enumerates three distinct actions with signatures. An agent can tell what each action returns (first match, all matches, polling result). It does not explicitly differentiate itself from the tc_app/tc_window siblings, which keeps it just shy of a 5.

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 clear per-action intent: find_object for the first match, find_objects for all matches, wait_for_object_displayed for polling until appearance. It also routes to tc_session(action="list_connections") for connection selection and explains the root_ref-vs-connection_id choice. No explicit 'when not to use' or named alternative tool, so not a 5.

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