Notematics

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

Annotations already declare a non-destructive write, and the description adds real context consistent with them: nothing on the board is changed or removed, the teacher can undo, and text with errors is silently not added. It doesn't say what the call returns on success, so the picture is nearly but not fully complete.

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 is front-loaded and every sentence carries scope, mode, prerequisite, or safety information. The inline quoted place labels make it read slightly like prose notes rather than a clean spec, but 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 mutation tool with full annotation coverage and no output schema, the description covers what is added, where it lands, the validation gate, and reversibility. The main residual gap is any statement about the response or what happens to the live link session after the addition.

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 the schema already documents all three parameters, including the same explanation of the place enum. The description restates place with added illustrative examples, which is modest value over the schema, and says nothing extra about link or text beyond what the schema covers.

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: it adds board text to the board the teacher currently has open, behind a live link. It is distinguishable from check_board (a prerequisite) and implies it is not a full-board replacement like publish_board, but it never names publish_board or read_board as alternatives.

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?

Gives concrete when-to-use guidance through the two place modes and their intents (next step/hint/drawing vs exercises/answers/new topic), plus a hard prerequisite: call check_board first or the text is rejected. It lacks an explicit rule for when to use this instead of publish_board.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description reinforces the non-publishing nature while adding real behavioral context: the return value includes per-page interpretation and error line locations with remediation hints, and the tool is meant to be called iteratively. It doesn't discuss size limits or how warnings differ from ERRORs, which keeps it short of a 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?

Three short sentences, front-loaded with what the tool does, then what it returns, then the workflow. No filler, no repetition of the title, and each sentence carries distinct 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 single-string validation tool with no output schema, the description covers purpose, return shape, and the retry/publish workflow, which is essentially everything needed to call it correctly. Minor gaps remain around error severity semantics and any input size constraints, but the schema's maxLength and format prose compensate.

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 text parameter's schema description already enumerates the Notematics syntax, fences, blocks and marks in detail. The tool description adds no additional meaning about the text parameter, so the 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 ('Checks a board text') and immediately scopes it against the sibling publish_board by saying 'without publishing it'. It also describes the output shape — parsed page-by-page understanding plus errors with line numbers — so an agent can distinguish it from read_board or publish_board without opening a 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?

Gives an explicit loop: fix every ERROR, call check_board again, and when there are no errors call publish_board. The condition that selects the alternative tool is named directly, leaving nothing to inference about when to stop checking and start publishing.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds one thing beyond them: that the return is a text format accompanied by a complete worked example, which is meaningful given there is no output schema. It says nothing about the size of that example or whether the format is stable across calls, which is the remaining useful detail.

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, zero waste, with the primary action and return content front-loaded before the usage qualifier. Every clause carries information an agent would act on.

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-parameter, non-destructive reference tool with no output schema, the description covers what it returns and when to call it, which is essentially everything an agent needs. The only omission is an indication of how large the returned example is, which could matter for context budgeting.

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 and the schema is empty with additionalProperties=false, so there is nothing for the description to disambiguate. A baseline 3 applies; no parameter meaning is added or 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 and resource ('Returns the Notematics text format') plus the shape of the payload ('with a complete example'), so the agent knows this is a format-spec lookup, not board content. It is clearly distinct from read_board and add_to_board, though it never names a sibling explicitly.

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?

'Read it before writing a board' gives an explicit trigger, and 'unless you already have it' gives an explicit exclusion, which is unusually good routing guidance for a reference tool. It stops short of naming add_to_board as the operation this is a prerequisite for, so the linkage 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by signaling that the list is current-state and time-sensitive ('now') and that availability is bounded per language, which affects how an agent should react to a missing language.

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 core action and followed by the returned fields, the availability constraint, and the hand-off to publish_board. No filler; 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, the description carries the burden of describing the return shape, and it does so explicitly: per-language voice list with id, name, gender, and default. Combined with the zero-parameter schema and existing annotations, nothing needed to call or interpret this tool is 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?

The tool takes zero parameters, so the baseline is 4 and nothing in the schema requires compensation. The description correctly implies the listing is site-scoped and unfiltered rather than describing any input options.

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 ('Lists the voices this Notematics site can voice narration with now') and enumerates what each entry contains: id, name, gender, and the language's default voice. An agent knows exactly what this returns, and it is clearly distinct from the board-oriented siblings.

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?

Gives a concrete downstream workflow: pick a voice here and pass it to publish_board as narration_voice. It also states a real constraint ('A language that is not listed cannot be voiced now'), which tells the agent what to do when a target language is absent. No explicit exclusions or alternatives are named, but there are no real alternatives among the siblings.

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?

Annotations already declare this is a non-read-only, open-world, non-destructive, non-idempotent operation, so the bar is lower; the description still adds real behavior: a link is returned, invalid boards are rejected with problems instead of publishing, and narration only activates when narration_language is supplied. The instruction to pass the link through verbatim hints that the URL is opaque or signed. It does not address what happens on a second publish of the same board, which matters given idempotentHint=false.

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 action and its return value are front-loaded, and the prerequisite and failure case follow immediately. The narration sentence restates the same fact twice ('the :::say blocks are voiced, so that the presentation plays with a voice'), which is the only wasted phrasing in an otherwise tight definition.

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?

There is no output schema, so the description must describe the return value, and it does: a link for the browser, or the board's problems on failure. For a five-parameter publish tool with full schema coverage, nothing an agent needs in order to call it correctly is 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 description coverage is 100%, so the schema already carries the parameter semantics and a baseline of 3 applies. The description adds the cross-parameter effect (narration_language voices the :::say blocks) but leaves autoplay, narration_speed, and narration_voice entirely to the schema rather than reinforcing defaults or interactions.

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 ('Publishes a board') and goes further by naming the observable outcome: it returns a link that opens in the user's browser. Naming check_board as the prerequisite action separates it from the sibling validation tool, so an agent can tell which of the six siblings to call.

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?

There is an explicit ordering rule ('Call check_board first') and a stated failure mode ('A board with errors is not published: the problems come back instead'), which is strong when-to-use guidance. It never contrasts publishing against add_to_board or read_board, so an agent must infer when to publish versus incrementally modify an existing board.

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?

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, and the description adds substantial context beyond that: lossy extraction (ink, images, widgets dropped), retention of narration as :::say, companion and mood markers, markup for strike/circle and styled spans. It also discloses that live links report the teacher's current page, a behavior not derivable from schema or annotations.

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?

Purpose and return format are front-loaded in the first clause, before the enumeration of markup. The single long sentence with a deep parenthetical is dense and less scannable than it could be, but essentially every clause carries information the agent needs about the lossy return format.

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?

There is no output schema, and the description compensates by describing the returned text format, the content that is dropped, and the markup conventions used. For a one-parameter read-only tool, nothing an agent needs in order to interpret or use the result is 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 100% and the schema already documents the live vs shared link forms with examples. The description still adds meaning by tying parameter type to outcome ('For a live link it also says which page the teacher is on'), clarifying why the distinction matters functionally.

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 ('Reads the board behind a Notematics link') and immediately says what comes back ('returns it as board text, in the same format you write'). The phrase 'in the same format you write' implicitly steers away from a format-definition sibling like get_board_format, but no sibling is named explicitly.

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 trigger is implied rather than stated: it operates on 'a Notematics link the user gave you', which suggests when the tool applies. There is no explicit when-not guidance and no mention of alternatives such as check_board or get_board_format, leaving the agent to infer routing.

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