goodnotes_plan_study_board

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds substantial behavior beyond that: it measures text, wraps lines, rejects overflow/overlap, and saves both a preview and an immutable execution plan. The immutability of the plan is a meaningful trait for downstream callers. What is missing is the failure mode (does rejection throw or return diagnostics?) and whether anything is persisted to the board itself.

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?

Three dense sentences, front-loaded with the purpose before the mechanics, and the closing note about caller-supplied semantic content earns its place by heading off a false expectation. No filler, though the middle sentence packs four distinct behaviors into one clause chain.

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 tool with a large nested schema, no output schema, and zero schema descriptions, the definition covers the conceptual model but leaves real gaps: the meaning of workflowId, how the saved preview is later retrieved or referenced, and what a rejection looks like. Adequate to understand intent, not sufficient to call it correctly without opening the schema.

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?

Schema description coverage is 0% over a deeply nested object (cards with role/heading/body/pages/span, figures with normalized crop rectangles, layout flow/columns/imageMaxHeight), and the description does not compensate. The phrase 'summaries, original PDF figure crops, questions and answers' loosely maps to card roles and figures, and 'Semantic content is supplied by the caller' usefully clarifies that the tool does not generate content. But key semantics — what workflowId is, what units layout.imageMaxHeight uses, how crop coordinates are interpreted — remain undocumented.

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 names a specific verb and resource ('Plan a source-based native learning board locally') and enumerates the content it plans: summaries, original PDF figure crops, questions and answers. It also frames the tool as a pre-write stage ('before writing'), which separates it conceptually from the run/prepare siblings. It never names an actual sibling, so an agent comparing goodnotes_plan_study_board against goodnotes_plan_study_collection or goodnotes_plan_layout still has to infer the split from the name alone.

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?

'before writing' implies the ordering constraint that this planning step precedes execution, which is real usage context. However, there is no explicit when-not guidance, no mention of what to do if the plan is rejected, and no routing to alternatives such as the revision or collection planners. Usage is implied rather than stated.

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