Research Execute

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

Annotations already declare openWorld=true, readOnly=false and non-idempotent, so the agent knows this mutates external state. The description adds real value beyond that: byte-checking of supplied originals, fail-closed behavior on unknown price ceilings, and the explicit rule that model tiers never establish CONFIRMED. It does not, however, describe run_id reuse or revision/pagination behavior.

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?

Seven short sentences, each carrying a distinct rule, with the prepare/execute scope front-loaded. The telegraphic style ('Unknown price ceilings fail closed') is dense but not padded.

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 complex nested schema with an output schema and annotations present, the description covers the safety envelope (authorization, dry-run, fail-closed) that structured fields cannot convey. It omits run_id/resume semantics and mode-to-field mapping, but nothing critical for a correct first call is missing.

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% and there is effectively one nested request object, so the baseline is 3. The description implies the mode semantics (URL execution vs inference) but does not map any of that to named fields such as mode, authorize_source_access, or dry_run.

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 pair and resource ('Prepare or execute source-preserving research') plus the scoping constraint of a single global allowance, which distinguishes it from lightweight siblings like research_plan or research_web. It stops short of naming which sibling to choose instead, so it is clear but not fully differentiated.

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 concrete conditional guidance: dry runs trigger no provider/URL calls, URL execution needs source-access authorization, inference needs submission authorization, and Google hosted research is a separate route. This tells an agent when routes are permitted, though it never names an alternative sibling tool to route to.

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