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

With no annotations, the description must carry the full burden. It usefully discloses the coordinate source and a verify-after loop, which is real behavioral guidance, but says nothing about what happens on a failed click, whether the action is immediate/irreversible, or what the coordinate space actually is.

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 short sentences, front-loaded with the action, then the applicability, then the verification step. Every sentence adds information; nothing is redundant.

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 mutation-style tool with no annotations and no output schema, the description covers the practical workflow end to end: obtain coordinates, click/drag, re-screenshot to verify. Only failure/rejection semantics and the optional drag parameter behavior are missing.

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 coverage is only 20% (just `ref`), so the description has to compensate. It does clarify that x/y are page coordinates sourced from beook_screenshot and that drag is an option, but it never explains the drag_to_x/drag_to_y pairing, units, or whether a drag requires both optional params.

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 concrete action (click or drag) against a specific resource (page coordinates in an exercise), so the agent knows exactly what the tool does. It is distinguishable from siblings like beook_fill_answers and beook_screenshot, though it never explicitly names those alternatives as the 'wrong' choice.

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?

"For drawing, arrow and image exercises" scopes when to use it versus the answer-filling tool, and "Take a new screenshot afterwards to check" prescribes a follow-up step. It gives clear context and an explicit prerequisite (coordinates from beook_screenshot), but no explicit exclusions or named alternatives.

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

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

With no annotations, the description carries the full burden. It discloses persistence ('beook saves them like typed input'), the open-exercise state requirement, and important overwrite semantics such as 'others get unticked' for multiple-choice fields and '[] empties it' for dropzones. Gaps remain around error handling for invalid handles and whether any response or confirmation is returned.

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 core action and persistence behavior are front-loaded in the first clause, followed by compact per-field-kind rules. The semicolon-separated format is dense but organized; every clause conveys necessary invocation detail rather than filler.

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 mutation tool with no annotations and no output schema, the description covers the essential behavioral complexity: field-kind-specific formats, persistence, and partial overwrite rules. It would be more complete if it stated that ref comes from beook_read_exercise and described what happens when a handle is invalid or the exercise is not open.

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 only 50%, and the value parameter has no schema description at all. The description compensates thoroughly by explaining exactly what value format to use for each field kind: text with \n, option label or handle for single_choice, list of ticked options for multiple_choice, text for select, pool item text/handle for dropzone, and ordered list for order.

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: 'Write answers into the open exercise'. This clearly distinguishes it from sibling read/open tools, though it does not explicitly name those siblings. The purpose is unambiguous without opening the schema.

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 phrase 'the open exercise' implies that beook_open_exercise must be used first, but this is never stated explicitly, nor is the relationship to beook_read_exercise for obtaining the ref. No when-not-to-use guidance or alternatives are given, leaving the agent to infer prerequisites.

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

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

With no annotations, the description carries the full disclosure burden, and it does add value by saying restart will 'close it normally' — a hint that unsaved state is handled gracefully. However, it omits what the agent should expect operationally: whether the call blocks until the app is ready, how long it may take, what happens on failure (not installed, port conflict), and what is returned.

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 short sentences, front-loaded with the primary action and followed immediately by the one conditional case. Nothing is repeated and every clause carries information.

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 zero-required-param launcher with a single optional flag and no output schema, the description covers purpose and the restart case adequately. What is missing is outcome information an agent needs to act on the result — whether success means the app is ready to use, and how failures surface.

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 coverage is 100% and the schema already describes restart as 'Close a running beook and reopen it.' The description's only addition is the pre-condition (already running *without the debug connection*) that should trigger restart=true, which is a marginal but genuine clarification of when the flag applies.

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 uses a specific verb ('Start') on a specific resource ('beook') and qualifies the goal ('with the debug connection this server needs'), which explains why this tool exists rather than just launching the app. It does not explicitly name sibling alternatives, but the intent is unmistakable against tools like beook_status or beook_click.

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 gives a concrete conditional: if beook is already running without the debug connection, pass restart=true. That is real when-to-use guidance tied to a runtime state. It stops short of stating the default path (call with no args when beook is not running) or what to do if it is already running correctly, both of which are only implied.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is in disclosing the return payload: chapters plus completed-exercise counts. That is meaningful behavioral context an agent cannot get from the annotations or the empty schema. Minor gap is no note on ordering or volume of results.

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?

One sentence, front-loaded with the primary action and followed immediately by the shape of the result. No filler or restatement of the tool name alone.

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?

With no output schema and no parameters, the description carries the burden of describing the return value, and it does so (chapters, completed exercise counts). It is nearly complete; only ordering, pagination, and error/auth conditions are unaddressed.

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 tool takes zero parameters, so there is nothing for the description to explain beyond call semantics; baseline of 4 applies. The description correctly implies no filtering inputs are needed.

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 (List) and resource (books/courses) and even clarifies the domain synonym 'courses', which disambiguates terminology. It does not explicitly contrast itself with beook_list_exercises, but the resource named is distinct enough that an agent can tell them apart.

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?

Usage is only implied: this is the natural entry point to survey available books and progress. There is no explicit statement of when to prefer it over beook_list_exercises or beook_status, and no prerequisites are mentioned.

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

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

readOnlyHint=true already declares the safety profile, so the description needn't restate it. It adds value by disclosing the returned fields, but leaves open what happens when course/chapter are omitted (all three params are optional) and whether results are scoped or paginated.

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?

A single front-loaded sentence with no filler; the resource comes first and the enabling detail follows. Every clause carries information an agent needs.

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?

With no output schema, naming the returned fields is a useful compensation. However, for a tool with three optional filters and zero required parameters, the description doesn't explain default scoping behavior when course or chapter are omitted, which an agent needs in order to call it correctly.

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 100%, so every parameter is already documented with an example id, which sets the baseline at 3. The description adds only marginal meaning, mainly clarifying that 'reference' and 'done state' are output fields linked to the only_open filter.

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 (list exercises) plus the exact fields returned (reference, number, title, done state), which lets an agent tell it apart from beook_list_books. It also ties itself to beook_open_exercise as the consumer of the reference, though it doesn't explicitly contrast with beook_read_exercise.

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 parenthetical 'needed for beook_open_exercise' implies a workflow position, but there is no explicit when-to-use guidance, no exclusions, and no statement of when to prefer beook_read_exercise or beook_list_books instead. Usage must be inferred from the workflow hint.

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

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

With no annotations, the description carries the full burden; it does convey that this is a stateful navigation action ('go to the next/previous exercise ... from the open exercise') and that it returns the exercise content. However, it does not say what state is changed (current position, progress, answers) or whether the operation requires an authenticated/launched session.

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 short sentences, verb and resource front-loaded, with the alternative navigation mode and the return behavior stated compactly. Nothing is wasted.

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 three-optional-parameter tool with fully documented schema and no output schema, the description covers the mechanics adequately. It leaves the overlap with beook_read_exercise unresolved and says nothing about the state left behind after opening, which matters for a UI-driving tool.

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 coverage is 100%, so ref, course, and direction are already documented in the schema, including the enum and the ambiguity condition for course. The description only adds the provenance of ref (from beook_list_exercises) and the fallback baseline for direction, which is a marginal gain.

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 (open) and resource (exercise) and covers both modes: open by reference or step next/previous. It does not distinguish itself from the sibling beook_read_exercise, which likely also returns exercise content, so an agent cannot fully disambiguate the two from this text 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?

Points to the prerequisite source of references (beook_list_exercises) and explains the two invocation modes, including that direction navigation starts from ref or the currently open exercise. It gives no exclusions or guidance on when to prefer beook_read_exercise instead.

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

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

The readOnlyHint annotation already makes clear this is a non-mutating read operation. The description adds useful detail by naming the returned content, but it does not disclose edge-case behavior such as what happens when no exercise is open, nor does it describe freshness or scoping behavior beyond the schema defaults.

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 a single well-structured sentence that front-loads the action and scope, then lists the returned information. Every clause contributes without repetition.

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?

With no output schema, the description does important work by enumerating the main return contents. Combined with complete parameter descriptions in the schema and a readOnly annotation, it is nearly complete, though it could specify behavior when no exercise is currently open.

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 100%, and both parameters are documented in the schema, including the default behavior for 'ref'. The description does not add meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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 states a specific verb and resource: reading the exercise currently open in beook, and enumerates what is returned (instructions, inline answer fields and current values, answer pool). The phrase 'currently open' helps distinguish it from opening or listing exercises, though it does not explicitly name sibling tools.

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 'currently open' phrasing implies when this tool is appropriate, but there is no explicit guidance on when to use it instead of beook_open_exercise or beook_list_exercises, nor any stated prerequisites or exclusions.

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

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

readOnlyHint=true is consistent with a screenshot operation, so the annotation bar is low. The description nonetheless adds a genuinely non-obvious behavioral fact: image pixel coordinates map 1:1 to page coordinates, which is essential for correct downstream use. It omits return format (image block vs. path/base64) and what happens when no exercise is open, keeping it below 5.

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 short sentences, both front-loaded and free of filler. The core action comes first and the coordinate note follows as supporting detail.

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 simple, read-only, single-parameter tool whose schema is fully documented, the definition covers the essential gaps, notably the coordinate system of the returned image. Missing only the failure mode (no exercise currently open) and the shape of the returned image.

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 single 'ref' parameter is fully documented in the schema (100% coverage, default = last opened exercise). The description says nothing about 'ref' or about how the screenshot target is scoped, so it adds no meaning beyond the schema. Baseline 3 applies.

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: 'Take a screenshot of the open exercise page.' It also names the downstream consumer (beook_click), which links it into the workflow. It doesn't explicitly distinguish itself from other read-oriented siblings like beook_read_exercise, but the verb+resource pairing is unambiguous.

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?

Usage is implied rather than stated: the mention that pixels can be passed to beook_click sketches a screenshot-then-click workflow. There is no explicit when-to-use condition, no exclusions, and no comparison against alternatives such as beook_read_exercise or beook_status.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The word "Check" implies a read-only status operation, and the description says what is reported, but it does not describe output format, failure behavior when beook is unreachable, or whether any side effects occur.

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 a single front-loaded sentence with no wasted wording. It immediately states the core check and then the additional status information returned.

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 simple zero-parameter status tool, the description is nearly complete: it says what is checked and what open state is reported. However, because there is no output schema, it could more explicitly describe the return shape or what an unreachable/not-running state looks like.

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 tool takes zero parameters, so the schema is empty and there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description correctly does not invent parameter details.

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 states a specific check of whether beook is running and reachable, plus which books/exercises are currently open. This is distinct from sibling tools such as beook_list_books, beook_open_exercise, and beook_read_exercise because it reports current status rather than listing or manipulating content.

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 implies when to use it—when you need to verify beook connectivity or see what is currently open—but it does not explicitly name alternatives or exclusions. It never says, for example, to use beook_launch when beook is not running or to use list tools for broader enumeration.

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