goodnotes_select_match

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

Annotations already declare a non-read-only, non-destructive, open-world operation, and the description adds the useful verification behavior (pixel check plus text read) and the return shape ('returns text and selection handles'). It doesn't say what happens to an existing selection, whether the check is costly or slow, or what error form a rejection takes. Decent added value over the annotations, 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?

Two tight sentences, front-loaded with the action, then the verification behavior, then the failure mode and return value. No wasted wording.

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?

For a two-parameter selection tool with no output schema, describing the return value and the rejection rule is genuinely helpful, but leaving both parameter meanings undocumented means an agent must guess how to construct the call. Adequate overall, with a clear parameter-semantics gap.

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?

With schema description coverage at 0% across two parameters, the description carries the full burden and does not meet it: matchId and expectedText are never named, and the format of an id or the role of expectedText (presumably the text to verify against) must be inferred. Only the vague phrase 'previously found' gestures at matchId.

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 gives a specific verb (select) and a specific resource (a previously found text object), and it is clearly distinguished from generic selection siblings such as goodnotes_select_object and goodnotes_select_board_match by the repeated emphasis on 'text' and 'editable'. It falls short of a 5 only because it never says where the 'previously found' object comes from.

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?

It states a prerequisite ('previously found') and an exclusion ('Rejects non-editable PDF/handwriting matches'), so an agent can tell when this call will fail and when not to use it. It stops short of naming an alternative tool for non-text objects or handwriting.

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