media_extractor

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

With no annotations provided, the description must carry the behavioral disclosure burden. It does disclose some behavior: extraction includes nested iframes, player_control operates 'via player API', and decode_url 'inspect[s] converted string and token formats.' However, it does not explain important behavioral aspects such as return values, side effects of switching iframes, what batch_extract returns, or how aiOptimize changes behavior. It is minimally adequate but not rich.

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 a single dense sentence that front-loads the core purpose and then compactly lists the six actions with brief parenthetical explanations. There is no filler or redundancy. It is concise and easy to scan, though a bulleted structure could have improved readability given the multi-action nature.

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?

This is a 14-parameter, 6-action tool with no output schema and no annotations, so the description carries a heavy completeness burden. It outlines the actions but omits critical invocation context: which parameters are required for each action, what the output shape is, how iframe switching is resolved, and how decode_url parameters should be supplied. The description is a useful summary but not complete enough for an agent to confidently invoke many of the actions.

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 71%, so the description is expected to add meaning for the remaining gaps and for cross-parameter relationships. It names actions like batch_extract, decode_url, and player_control but does not clarify which parameters apply to which actions, how decoderKey/decoderIV/encodedData interact, or how index/selector relate to iframe actions. The action names mostly repeat the schema enum, adding little parameter-level value.

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 starts with a specific verb-resource pairing: 'Extract and control media from the current page.' It then enumerates six concrete actions, which clearly differentiates this tool from the sibling set (e.g., get_content, network_recorder, extract_data). The purpose is immediately understandable and not a mere restatement of the tool name.

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 lists supported actions but provides no guidance on when to use this tool instead of sibling alternatives like network_recorder, extract_data, or execute_js. There are no explicit conditions, exclusions, or routing hints. Usage context is only implied by the phrase 'from the current page' and the action list.

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