scroll
Scroll screen content at specified coordinates in any direction. Use this macOS automation tool to navigate documents, web pages, or applications by controlling scroll behavior programmatically.
Instructions
Scroll at the specified screen coordinates in the given direction. Do not narrate visual observations or coordinate calculations. Brief task progress updates are acceptable.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | X coordinate in screen pixels (may be negative for secondary displays) | |
| y | Yes | Y coordinate in screen pixels (may be negative for secondary displays) | |
| direction | Yes | Scroll direction | |
| amount | Yes | Scroll amount in discrete steps (default: 3) |
Implementation Reference
- src/tools/mouse.ts:268-293 (handler)The handler function for the "scroll" tool, which parses input, calculates deltas, and invokes the scroll helper.
async function handleScroll( args: Record<string, unknown>, ): Promise<CallToolResult> { const parsed = ScrollInputSchema.parse(args); const { dx, dy } = scrollDirectionToDeltas(parsed.direction, parsed.amount); const result = await runInputHelper("scroll", { x: parsed.x, y: parsed.y, dx, dy, }); const response: Record<string, unknown> = { scrolled_at: { x: parsed.x, y: parsed.y }, direction: parsed.direction, amount: parsed.amount, }; if (typeof result.warning === "string") { response.warning = result.warning; } return { content: [{ type: "text" as const, text: JSON.stringify(response) }], }; } - src/tools/mouse.ts:81-110 (schema)Input schema definition for the "scroll" tool.
const ScrollInputSchema = z.object({ x: z .number() .int() .describe( "X coordinate in screen pixels (may be negative for secondary displays)", ), y: z .number() .int() .describe( "Y coordinate in screen pixels (may be negative for secondary displays)", ), direction: z.enum(SCROLL_DIRECTIONS).describe("Scroll direction"), amount: z .number() .int() .positive() .max(SCROLL_MAX_AMOUNT) .default(SCROLL_DEFAULT_AMOUNT) .describe( `Scroll amount in discrete steps (default: ${SCROLL_DEFAULT_AMOUNT})`, ), }); const DragInputSchema = z.object({ start_x: z .number() .int() .describe( - src/tools/mouse.ts:163-171 (registration)Registration of the "scroll" tool in the mouse tool definitions.
{ name: "scroll", description: `Scroll at the specified screen coordinates in the given direction. ${SILENT_HINT}`, inputSchema: zodToToolInputSchema(ScrollInputSchema), annotations: { readOnlyHint: false, destructiveHint: false, }, },