flutter_locate

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

With no annotations, the description carries full responsibility for behavioral disclosure. It reveals that tap coordinates come from Android's semantics tree and source location from Dart VM Service, and clarifies that the text parameter may match visible text, semantics label, or widget type. It doesn't state preconditions like needing a connected Flutter app, but the mention of Dart VM Service implies an active debug session.

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 first sentence is a sharp summary. The second provides useful context about how the tool works and why it matters. The Args section is compact and clear. Every sentence adds value; no filler or redundancy.

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 relatively simple (3 parameters, output schema present) and the description covers the core workflow, input semantics, and the two data sources. It stops short of specifying failure behavior (e.g., no match found) or explicit prerequisites like a prior flutter_connect call, but the intended usage is fully understandable.

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 explain parameters. It effectively explains the required 'text' parameter (visible text, semantics label, or widget type) but passes off package and serial as 'as elsewhere,' relying on external convention. This leaves a gap for an agent that doesn't already know the established device-targeting parameters, though they are relatively self-explanatory.

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 opens with a specific verb and resource: 'Find something on screen' and reports both 'how to tap it and where it lives in code.' It goes further by naming the exact data sources (Android semantics tree and Dart VM Service), clearly distinguishing it from Flutter widget tree, UI dump, and tap tools. This is a model of a clear, differentiated purpose.

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 description gives a concrete scenario: 'go from this looks wrong on screen to the exact line that built it.' This implies when to use the tool, and the bridge metaphor explains why it is different from other UI inspection tools. It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough that an agent can select it appropriately.

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