Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

live_select

Select a paragraph in an open Word document by address or find phrase, returning its text and address.

Instructions

Select a paragraph in the app's window, by address (at) or by a locate find phrase, and return its text and address.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atNoParagraph address, e.g. `p142#a7b2a7b2`.
docYesPath to the document, or the file name of one open in a live app.
modeNo`select` (default) selects the paragraph; `cursor` only puts the cursor at its start, so typing or Delete cannot replace it.
frontNoBring the app's window to the front (default true); the reply's `front` says whether it came.
engineNoAlways the live engine; may be left out.
find_phraseNoA phrase that occurs once in the document (`\r` for a paragraph mark), as `locate` gives it.
match_levelNoHow loosely `find_phrase` matches. `default` (the default) ignores case, accents and punctuation; `loose` symbols too. Either tries the levels from verbatim on and takes the first that matches, so one verbatim paragraph beats looser ones. `exact` is `locate`'s rule: case ignored, nothing else, no retry. Two meanings of exact: the request's `exact` allows a case difference, the reply's does not. The reply's `match_level` (`exact` character for character, `case`, `default`, `loose`) names the level that matched, with `matched_text` when it is not `exact`.
paragraphs_afterNoSelect the paragraph this many after the one named.
find_phrase_acrossNo`locate`'s `find_phrase_across`, for a phrase spanning a mark.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations carry readOnlyHint=false, so the agent already knows this is not a pure read, and the description's 'Select a paragraph in the app's window' is consistent with that. However, it never discloses the real side effect - that it changes the app's current selection/cursor and may bring the window to the front - although the schema's `mode` and `front` descriptions partially cover the latter. Adds modest context beyond annotations; no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence that front-loads the action, both selection mechanisms, and the return value, with zero filler. Nothing needs trimming and nothing essential is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description sensibly states what comes back ('its text and address'), which is the key missing piece. With nine parameters at full schema coverage and enums carrying the behavioral detail, the remaining gap is the undisclosed effect on the live app's selection state.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and four enums are fully documented, so the baseline is 3. The description adds only a shallow hint ('by address (`at`) or by a `locate` find phrase') and even refers to `locate` rather than the actual `find_phrase` parameter, so it contributes little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (select) plus resource (a paragraph) and scope (in the app's window), with the two addressing mechanisms (address or find phrase) named. It is clear what the tool does, but it never names or contrasts with near siblings like para_get, locate, find, or live_selection, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The sentence implies the two ways to identify a paragraph (`at` vs a locate find phrase), but gives no when-to-use or when-not guidance and no comparison to alternatives such as locate, find, para_get or live_selection. An agent must infer when selecting in the live app is preferable to just reading text.

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

Deploy Server

Other Tools