find_text_on_screen

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

With no annotations, the description carries the behavioral burden. It discloses the core behavior — searching the screen and returning a location — but it does not define what 'location' means (e.g., x/y coordinates, bounding box), how multiple matches are handled, or whether it relies on OCR.

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 sentence with no filler: the action and return value are front-loaded. It is appropriately sized for a simple two-parameter tool.

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?

The tool is simple, but there is no output schema, so the description should clarify the return value format. Saying 'location' is incomplete for an agent that may need to pass coordinates to click_at_position, and the description does not disambiguate from extract_text_from_screen.

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 and no additional parameter documentation is required. The description adds no parameter-specific detail, but the schema already fully describes 'text' and 'case_sensitive'.

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 states a specific action ('find text on screen') and its result ('return its location'), which is clearly distinct from the sibling capture and text-extraction tools. It does not explicitly contrast with extract_text_from_screen, but the search-and-locate behavior is identifiable.

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?

The phrase 'find text on screen' implies use when the agent needs to locate a specific string rather than extract all text or capture the screen. However, there is no explicit when-to-use guidance, exclusion criteria, or mention of sibling alternatives.

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