find_widget

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

No annotations are provided, so the description carries the full behavioral disclosure burden. The description discloses the dual-mode lookup strategy (index-then-fallback), which is useful behavioral context, but doesn't mention performance characteristics, whether the fallback search could be slow over large codebases, or what happens if the widget is not found.

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, efficient sentence that conveys the verb, resource, and strategy. No wasted words; information is front-loaded. Could potentially add a sentence on usage guidance but remains appropriately compact.

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 has 3 parameters, no annotations, and no output schema, so the description is the primary documentation. It explains the lookup strategy but leaves gaps: what does 'limit' limit, what does the result look like given no output schema, and when should the agent choose filesystem search vs index. Adequate but not complete for a tool of this complexity.

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 67%: 'name' and 'repository' have descriptions, but 'limit' has only type constraints (maximum 100, exclusiveMinimum 0) with no semantic explanation of what it limits (widget matches? search depth?). The description adds the strategy context but does not clarify the 'limit' semantics or the format/behavior of 'repository' beyond the schema.

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?

Uses a specific verb 'Locate' with a clear resource ('Flutter widget by name') and describes two search strategies (SQLite index vs filesystem). It distinguishes reasonableness from sibling tools like find_examples/find_tests which target different resources. However, it does not explicitly contrast against siblings that might overlap, like search_source.

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?

Mentions that it uses SQLite index 'when available, else filesystem search,' implying when to use and providing fallback context, but gives no explicit guidance on when to prefer this tool versus alternatives like search_source or trace_widget. No exclusions or alternative recommendations are provided.

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