live_scroll_to

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

With no annotations provided, the description carries the burden of disclosing side effects and safety. It explicitly states the tool is 'Read-only', does not select anything, and does not move the cursor, which are the most important behavioral traits for a navigation command. It also notes that find targets the first match. It doesn't discuss not-found behavior or conflicts between the two target parameters, but the provided behavior is still substantially transparent.

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 two sentences of concentrated, relevant information. It front-loads the core action and side-effect-free nature, then adds targeting options and the prerequisite. Every clause adds value; there is no filler or redundant restatement of the tool name.

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 the tool's moderate complexity, the description covers the main purpose, targeting methods, use case, prerequisite, and read-only nature. An output schema exists, so the absence of return-value detail is not a gap. It could be more explicit about what happens when both find and paragraph_index are supplied or when no target is found, but the core information needed to invoke the tool correctly is present.

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?

The schema has 0% description coverage, so the description must compensate for all three parameters. It does: 'find text (first match)' maps to the find parameter, 'body paragraph_index' maps to paragraph_index, and 'document must be open in Word' clarifies the file_path target. This is strong compensation, though it leaves some ambiguity about parameter precedence and the meaning of 'body paragraph_index'.

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 clearly states the specific action ('Scroll the user's Word window'), the target resource (a Word document), and the key behavioral nuance (no selection, no cursor movement). It also distinguishes itself from related tools like live_insert_at_cursor and find_text by emphasizing it only navigates the view. This is more than enough for an agent to understand the tool's unique purpose.

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 gives a strong usage context: 'useful after a live edit to show the user what changed' and a clear prerequisite ('document must be open in Word'). It does not explicitly mention alternatives or when not to use it, but the intended scenario is clear enough for an agent to select it appropriately.

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