live_insert_at_cursor

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

No annotations are provided, so the description carries the full burden. It does this well by disclosing that the cursor is read once, never moved, and the user's selection is untouched, plus the newline behavior and unsupported document areas. This gives the agent a clear model of side effects and limitations.

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 compact and front-loaded with the main action, followed by scope, behavioral guarantees, alternative routing, and prerequisite. Every sentence contributes necessary information without padding.

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 presence of an output schema, return-value detail is unnecessary. The description covers what the tool does, where it operates, what it does to the cursor/selection, the main alternative, and the key prerequisite. The only meaningful gap is the missing semantic explanation of file_path as the identifier for the open document.

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?

Input schema descriptions are at 0% coverage, so the description must compensate. It explains the newline parameter ('ends the insertion with a paragraph break') and implicitly defines text as the inserted content, but it does not explain file_path beyond requiring the document to be open in Word. There is also no clarification of whether text may contain multiple paragraph breaks or how path resolution works.

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 and resource: 'Insert text at the user's cursor position in the open document.' It also draws a clear boundary by saying headers/footers/footnotes are not supported, which separates it from other insertion tools. The naming of insert_paragraphs as the alternative further disambiguates its 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 explicitly tells the agent when to use this tool versus an alternative: 'Use insert_paragraphs for index-addressed insertion instead.' It also gives the prerequisite that the document must be open in Word, which is actionable guidance for invocation.

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