Flett

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that content is authored from markdown, but says nothing about whether each call creates a distinct new block, position defaults, or editing implications for an existing block.

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 sentence, front-loaded with the core action and resource. The trailing list of example content types is a bit list-heavy but does useful disambiguation work, so it largely earns its place.

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 five parameters, 80% schema coverage, annotations present, and no output schema, the description covers the core purpose but omits what the tool returns (e.g., a block id needed for later edit_block/read_block calls) and gives no guidance on placement. Adequate but with visible gaps for a mutating 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 description coverage is 80%, with clear docs for boardId, title, markdown, and x (the y parameter is left undocumented). The description only reinforces that the content parameter is markdown, adding little beyond what the schema already states, 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 concrete action and resource: writing markdown content onto a Flett board as a 'document block', with a concrete list of content types. It distinguishes itself reasonably from add_file/add_map, though it never explicitly contrasts with the closest sibling add_block, which also creates content on a board.

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 enumerated content types (notes, explanation, report, comparison, study guide, plan) imply when this tool is appropriate, but there is no explicit routing guidance against add_block, add_file, or edit_block. The agent must infer the boundary between this and generic block creation.

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 declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the agent knows this is a local, non-destructive write. The description adds useful context on the html parameter (self-contained, may load only specific CDNs, cannot fetch data at runtime), but this is largely present in the schema too and the description omits side effects like what happens to existing blocks.

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 sentence that front-loads the core action and then enumerates representative block types. No wasted words, tight and well-structured.

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 9-parameter mutation tool with no output schema, the description is thin on prerequisites (auth, boardId source), coordinate semantics, and interaction with other block tools. It covers the html content constraint well but leaves gaps an agent would need filled.

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 78%, so the schema already documents most parameters including format enums and dimensions. The description adds the semantic distinction that a slide holds one block per deck slide, but doesn't clarify x/y, headFrom usage, or sizing rules beyond what the schema provides.

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 clear verb+resource ('Put a designed HTML block on a Flett board') with concrete examples of block kinds (slide, page, chart, mockup, card, diagram). This distinguishes it from siblings like add_file, add_map, and add_answer, though it doesn't name a specific alternative tool.

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?

No when-to-use or when-not-to-use guidance. The description lists content types but never tells the agent when to pick add_block over edit_block, add_file, or draw, nor does it state prerequisites like needing a boardId from list_boards.

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 mark this as a non-read-only, non-destructive, non-open-world write. The description adds useful behavior context: the appearance of the item depends on file type, and the two accepted sources for file content. It does not mention permissions, limits on file size, or what happens if the upload name is stale.

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 sentences, front-loaded with the main effect and followed by the source-of-file rule. No filler, though the second sentence compresses two alternatives into one clause without fully separating the cases.

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 6-parameter write tool with no output schema and no output described, the definition covers what the agent most needs: what gets created, how it looks, and where the file content comes from. Missing are error cases and whether an upload name expires, but those are beyond the typical scope of a description.

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 83%, so most parameters are already documented. The description still adds value by explaining the semantic difference between 'upload' (name returned by upload_file) and 'data' (raw base64 for small files), which is the key decision for the agent. It does not explain the coordinate behavior of x and y beyond the schema's own description.

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 concrete verb and resource ('Put an image or a document on a board') and explains the observable result: images render as pictures, documents render as file objects others can open and download. This distinguishes it from siblings like add_block or upload_file.

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 tells the agent that the file must come as an upload name from upload_file, or as base64 bytes for a small file. That implies a workflow with upload_file, but it does not state when to prefer base64 over an upload URL or when to use add_block 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the coordinate-format requirement; it says nothing about ordering, overflow when the place/route caps are hit, or how the new block interacts with existing board content.

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 with no filler; the core action and the content types lead, and the coordinate convention follows. Nothing is repeated or 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 6-parameter write tool with 83% schema coverage and full annotations, the description covers purpose and coordinate format adequately and no output schema exists to explain. It is only short of the top band because it omits any routing versus add_block/draw guidance and says nothing about the practical limits on map size.

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 83%, so the schema already documents nearly every field, including labels, notes, and ordering. The description adds the decimal lat/lng convention, which is marginal above what the schema's lat/lng fields already convey, 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 concrete verb+resource ('Put a map on a Flett board') and enumerates what the map contains (marked places, drawn routes), which distinguishes it from generic siblings like add_block or draw. It never names a sibling explicitly, so it falls short of the top band.

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 only directive is a parameter convention ('Give coordinates as decimal latitude and longitude'); there is no statement of when to choose this tool over add_block, draw, or edit_block, and no prerequisites or exclusions. The examples ('a trip, a set of locations, a region') hint at use cases but do not constitute guidance.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's remaining burden is light. It adds context annotations do not carry: the board is created empty and the result returns an id and link, which is genuinely useful given there is no output schema. It omits auth/permission or quota considerations, but for a simple creator that is a minor gap.

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 with zero filler, front-loaded with the action and outcome. Every clause earns its place.

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 one-parameter creation tool with annotations covering safety and no output schema, the description supplies the essentials: what is created, its initial state, and what is returned. Only optional context like permission requirements or how to subsequently populate the board 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 single 'title' parameter and its maxLength of 120 are fully documented in the schema. The description adds no extra meaning about the title (e.g., uniqueness or naming conventions), so the baseline of 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?

Clear specific verb and resource: 'Make a new, empty Flett board'. It conveys the created object's state (empty) and its intended use ('for a new topic'), which distinguishes it from sibling mutations like add_block or edit_block. It stops short of explicitly naming the complementary sibling list_boards, so sibling differentiation is implied rather than stated.

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 'for a new topic' implies the usage context (starting a fresh board rather than populating an existing one), which is more than nothing. However, there is no explicit when-to-use/when-not guidance, no mention of prerequisites, and no routing to alternatives such as list_boards for finding existing boards.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely non-obvious side-effect detail — that attached arrows and contents of a removed frame are preserved rather than deleted — which is exactly the kind of context annotations cannot express. It still omits irreversibility and any cascade behavior for subitems.

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 action and followed immediately by the non-obvious consequence. No filler, no restatement of the title.

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 two-parameter destructive tool with no output schema, the description covers the key ambiguity an agent faces with deletion — what happens to dependent objects. It is slightly thin on irreversibility and partial-failure behavior, but annotations carry the destructive warning.

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 only 50% schema description coverage, the description does not compensate at all: it says nothing about boardId or itemIds syntax, formats, or the 500-item batch cap. The parameters are largely self-describing by name, so this lands at the baseline rather than below it.

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: 'Remove items from a board.' That contrasts implicitly with move_items and edit_block in the sibling list, but the description never names an alternative to make the boundary explicit.

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 no when-to-use guidance, no prerequisites (e.g. required permissions), and no routing to alternatives such as move_items when the user actually wants relocation rather than deletion. The agent must infer the context entirely.

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=false, destructive=false, openWorld=false. The description adds genuinely useful context beyond that: content 'stays editable on the board' after drawing, the ref-to-arrow wiring model, and the fact that it returns each item's id (valuable since there is no output schema). It omits any permission or rate/limit caveats, keeping 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?

Four sentences, all substantive, with the action front-loaded in the first clause. The diagram-type enumeration is long but earns its place by aiding tool selection; 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 high-complexity tool with five oneOf item variants, a 100% documented schema, and no output schema, the description covers what it draws, post-state editability, the ref mechanism, and the return value. The main remaining gap is explicit routing against sibling creation tools.

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% (defaults, enum values, ref semantics, limits) and the two top-level parameters are documented in the schema. The description restates the ref/arrow-pointing workflow but adds no syntax or constraint detail beyond it, so the baseline 3 for a fully documented schema 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 verb and resource are precise ('Draw notes, text, shapes, frames and arrows on a Flett board in one call') and the enumerated item types plus diagram use-cases (flowcharts, mind maps, kanban) make the tool's remit unambiguous. However, it never names or contrasts with nearby siblings such as add_block, add_map, or set_text, so differentiation is inferred rather than stated.

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 through the diagram-type list and the 'in one call' batching hint, which tells the agent this is the bulk-diagramming entry point. There is no explicit when-to-use vs when-not guidance and no alternative tool is named, so the agent must infer the boundary with add_block/add_map.

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 destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds the uniqueness precondition, but that same constraint is already stated in the schema's `before` description, so it adds little beyond structured data. Nothing is said about what happens when the precondition fails or whether the edit is atomic.

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 filler, with the core operation front-loaded and the matching precondition immediately after. Every clause earns its place.

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 four-parameter destructive mutation with no output schema, the description covers the core operation and precondition but omits failure behavior (what happens if `before` is missing or ambiguous), and gives no hint of the result an agent should expect after the edit.

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 75%, so the baseline is 3. The description's explanation of `before` (the exact current HTML passage, appearing exactly once) largely restates the schema, and it adds nothing about boardId or the format of `after`.

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 (change/replace) and resource (part of an HTML block) plus the mechanism (exact-passage replacement), which is far more informative than the title alone. It does not, however, differentiate itself from siblings like update_block or set_text, leaving the agent to infer which is appropriate.

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: 'Change part of a block' suggests this is for surgical, partial edits rather than whole-block rewrites. No sibling is named as an alternative and there is no explicit when-not-to-use guidance, so the agent must reason about update_block vs edit_block vs set_text on its own.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description adds value beyond that by disclosing sort order (most recently changed first) and the exact fields returned (id, title, link, edit permission), which is genuinely useful since no output schema exists.

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 sentence, front-loaded with the resource and scope, then the ordering and return fields. Efficient, though the trailing list of return fields makes it slightly run-on rather than maximally tight.

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-param, read-only listing tool with no output schema, the description covers the essentials: what is returned, in what order, and with what fields. It omits pagination or result-limit behavior, which is the only notable 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?

The tool takes zero parameters, so the schema has nothing for the description to compensate for. Per the baseline for parameterless tools, a 4 is appropriate; the description correctly avoids inventing parameter semantics that do not exist.

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 resource (Flett boards) and crisply defines its scope: boards the person owns plus boards shared with them. It is clearly distinguishable from the single-board sibling read_board and the write-oriented create_board, though it never uses an explicit listing verb, relying on the noun phrase to imply retrieval.

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 no when-to-use guidance, no mention of alternatives such as read_board for a single board, and no stated preconditions. The scope wording implies the use case but nothing explicitly routes the agent.

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 idempotent=true, destructive=false, readOnly=false, but the description adds real operational context beyond them: attached arrows follow, a frame brings its contents, moving one group member moves the group, and locked items are unaffected. These are exactly the side effects an agent must anticipate before calling a bulk mutation.

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 sentences, front-loaded with the core operation and followed by the consequences that matter. Slight redundancy in 'in one call' and the run-on opening sentence keep it from being maximally tight, but there is no 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 bulk mutation with no output schema and a nested moves array, the description covers the key behavioral semantics (group/frame/locked handling) an agent needs. It stops short of describing the response or how partial failures are reported, which an agent would still want for a 200-item batch.

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 50% – only boardId is documented in the schema. The description compensates partially by explaining that x/y is the new top-left corner and width/height are optional, but it omits units, the 20–20000 size bounds, the 200-item batch cap, and partial-failure semantics, so it does not fully offset the coverage gap.

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 precise verb pair (move or resize) plus the resource (items on a board) and the exact geometric semantics (new top-left corner, optional width/height). This is specific enough that an agent can separate it from content-oriented siblings such as update_block, edit_block, or delete_items 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?

The phrase 'in one call' implies batch usage and the behavioral rules hint at when side effects apply, but the description never states when to choose this tool over a sibling, nor any prerequisites (e.g. that the board must exist or items be unlocked). Usage is implied rather than prescribed.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context not in the annotations: for HTML blocks it returns the full HTML plus 'what it keeps,' and for notes/shapes/frames it returns their fields. With no output schema, that disclosure is valuable.

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 compact sentence with no filler, and the item-type return behavior is front-loaded. Slightly dense phrasing ('what it keeps') costs a little clarity but wastes no words.

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 read-only item fetch with no output schema, the description usefully characterizes what comes back for each item type, and annotations carry the safety profile. Missing only error/permission behavior, which is minor here.

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 both parameters (boardId, blockId) are already documented in the schema, and the description adds no syntax, format, or constraint detail beyond that. 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 ('Read one item on a board') and scopes it to a single item, which implicitly separates it from the board-level read_board sibling. It stops short of naming read_board explicitly as the alternative, so the differentiation is inferable rather than stated.

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: 'one item' versus a board read suggests when to reach for this tool, and the schema notes the blockId comes from read_board, but the description itself gives no explicit when-to-use or when-not-to-use guidance.

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=true and openWorldHint=false, so the safety profile is covered. The description adds value by listing the returned item fields, but says nothing about ordering, pagination, size limits, or behavior on a large board.

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 compact sentence that front-loads the resource and lists return fields without filler. The phrasing 'title or words' is slightly ambiguous but costs little.

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 does so by enumerating the five fields per item. It is nearly complete for a simple read tool; the only gap is scale/ordering behavior, which an agent may still need.

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 single boardId parameter is fully documented in the schema, including its provenance from list_boards or create_board. The description adds no parameter-level detail beyond that, 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?

The description names the resource (a board) and enumerates what it returns (each item's id, kind, title/words, position, size), which implicitly distinguishes it from the singular read_block sibling. It never uses an explicit verb like 'retrieve' and relies on the title for the action, so it is clear but not maximally crisp.

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 no guidance on when to use read_board versus read_block, list_boards, or the many mutation siblings. The only implicit signal is that this covers all items on one board, but no condition or alternative is 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 readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered externally. The description adds no behavioral context of its own: it never states that existing text is overwritten, what permissions are needed, or what happens on an unknown itemId, so it contributes nothing beyond the structured hints.

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 tight sentence with the verb and target list front-loaded and no filler. It is appropriately sized for the operation, though it is arguably too terse for the gaps it leaves.

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 destructive mutation with no output schema and two of three parameters undocumented, the description should say more about overwrite semantics, target validity, and selection versus siblings. As written, an agent has enough to attempt a call but not enough to invoke it confidently.

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 33% (boardId only), so the description must compensate for the undocumented text and itemId. It partially helps by naming the item types that itemId can address, but gives no guidance on text constraints (2000-char max) or itemId format, leaving a real gap.

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 clear verb ('Change') plus the resource and enumerates the target types (note, text, shape, arrow label, frame name), so an agent can tell it edits text content rather than structure. It stops short of explicitly differentiating itself from siblings like edit_block or update_block, but the target list makes the scope reasonably distinct.

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 no when-to-use guidance and no mention of alternatives such as edit_block or update_block, which plausibly overlap. Usage is only implied by the list of editable targets, leaving the agent to guess which tool to pick for a block edit.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured data. The description's word 'whole' reinforces that existing content is fully overwritten rather than patched, which adds modest value, but it says nothing about permissions or side effects beyond that.

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 zero padding. It is efficient, though arguably terse to the point of under-specification.

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 destructive, 4-parameter mutation tool with 50% schema coverage and no output schema, one short sentence leaves too much unstated: no routing to or away from siblings, no guidance on the undocumented parameters, and no detail on the destructive overwrite.

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 50%, and the description adds little beyond the schema: 'whole HTML' loosely maps to the html field, which is already documented as 'The complete new HTML document'. The undocumented title and blockId parameters get no help from the description.

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 ('Replace') and resource ('the whole HTML of a block'), so the operation is unambiguous. It does not, however, distinguish itself from the nearby edit_block/add_block siblings, which an agent must choose between.

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 no indication of when to use this tool versus edit_block (partial edits) or add_block (creation), nor any prerequisites or exclusions. The agent must infer the difference from the name alone.

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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the description carries the interesting burden and delivers: it discloses the two-phase flow (a returned URL to PUT to), a ready curl command, and the upload name. That non-obvious 'you must complete the PUT yourself' behavior is exactly the kind of detail annotations cannot express.

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 sentences, front-loaded with the action and scope, followed by the return contract. Little waste, though the long format enumeration is the least essential part of the first sentence.

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 appropriately explains what comes back (URL to PUT to, curl command, upload name) alongside formats and the size limit. It is nearly complete for a 2-parameter tool; only the sibling relationship with add_file is left 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?

Schema description coverage is 100% for both parameters, so fileName and bytes are already documented with examples and the extension convention. The description's 'up to 10 MB' merely restates the schema maximum and adds no new per-parameter meaning, so 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?

The description names a specific verb and resource ('Start adding an image or document ... to a board') plus the exact accepted formats and size cap, so the action is unambiguous. It falls short of a 5 because it never distinguishes itself from the closely named sibling add_file, leaving the agent to guess which one applies.

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 by 'from the person's computer to a board,' which suggests this is the entry point for local file content. However, there is no explicit when/when-not guidance and no mention of the competing add_file sibling, which shares nearly the same name and purpose.

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