search_android_classes

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

The description adds real context beyond the annotations: duplicate names are preserved and surfaced in a duplicate_names group, artifact/engine identity is retained across results, and the target APK is never executed. It does not contradict destructiveHint=false or idempotentHint=true, though it never explains the readOnlyHint=false flag (presumably state retention via analysis_project_id), leaving an agent to infer why a search is not marked read-only.

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 purpose and the empty-query behaviour are front-loaded in the first two sentences, with caveats after. The middle sentence about duplicate names and provider lookup is dense and slightly tangled, but nearly every clause carries information an agent could not get from 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?

For a three-parameter read-style search with no output schema, the description covers what is searched, what an empty query returns, the duplicate-name return shape, and the no-execution guarantee. It stops short of describing result ordering, count limits, or what the retained artifact/engine identity looks like in the response — the main remaining gaps given there is no output schema to fall back on.

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 100%, so all three parameters are already documented, and the description largely restates the case-sensitive substring and empty-query semantics that the schema already states. The one genuine addition is the caveat that returned rows cannot identify which same-name class node a later lookup will select, which is about result meaning rather than parameter behaviour.

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 first sentence gives a specific verb (Search), a precise resource (complete decompiler class-name rows) and scope (an explicit local APK, case-sensitive substring). That is far more specific than a restated title. It never names the neighbouring tools it must be distinguished from (search_java, search_strings, search_procedures, inspect_android_class), so the differentiation is left implicit.

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?

"Empty query inventories all rows" is useful invocation guidance for the enumerate-everything case, and the note that the provider accepts only class names hints at a follow-up path. But there is no explicit when-to-use/when-not, no named alternative for searching Java source or strings, and no statement of when the optional analysis_project_id should be supplied.

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