site.execute

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

The annotations already disclose that the tool is not read-only, is open-world, and is destructive. The description adds useful context by clarifying that writes are user-authorized and execute directly in the browser, and that caching avoids repeating operations. It stops short of detailing permission requirements, side effects of different operation types, or error behavior, so it adds moderate value beyond the annotations.

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 three tight sentences that front-load the core action and then cover pagination and cached output. Every sentence contributes, though the cached-output sentence is slightly dense; overall it is efficient with no obvious filler.

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?

Given zero schema coverage, no output schema, and a complex multi-use tool with annotations, the description covers the main operational modes but omits details about what operations are discoverable, how args map to specific operations, and any error or permission handling. It is adequate but leaves clear gaps for an agent to call correctly in all cases.

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?

With schema description coverage at 0%, the description compensates by explaining key parameter semantics: targetId identifies the target, args must match the operation's exact schema, and resultId with offset/maxChars is used for cached output. It does not describe the 'operation' parameter's expected values or constraints, but overall adds substantial meaning beyond what the schema provides.

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 verb ('execute') and resource ('discovered operation on a targetId'), which distinguishes it somewhat from siblings like site.discover and site.context. However, 'a discovered operation' is vague without explaining what operations are available or how they are obtained, leaving the exact purpose slightly nebulous.

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 implies usage for writes ('User-authorized writes execute directly in the browser') and for pagination ('Pass returned pagination args') and cached output ('for cached oversized output pass only resultId, offset and maxChars'). Yet it does not explicitly state when to use this tool versus the siblings site.discover or site.context, or when not to use it, leaving the routing guidance incomplete.

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