miro-mcp-server

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.24.0
Disambiguation4/5
Despite 88 tools, each has a very specific purpose and detailed descriptions clarify differences. Some overlap exists between similar creation tools (e.g., miro_create_doc vs miro_create_text), but the descriptions effectively guide selection. Overall, an agent can distinguish tools with reasonable confidence.
Naming Consistency5/5
All tools follow a consistent 'miro_verb_noun' snake_case pattern. This makes the tool set predictable and easy to navigate. There are no deviations or mixing of conventions.
Tool Count1/5
With 88 tools, the server is far beyond the typical well-scoped range of 3-15. This extreme number suggests over-fragmentation and could overwhelm agents, increasing selection complexity and cognitive load.
Completeness5/5
The server covers virtually all Miro board operations: CRUD for every item type, board management, member management, export, search, bulk operations, tagging, auditing, and diagram generation. No obvious gaps exist; the surface is fully featured for the domain.
Average 4.1/5 across 88 of 88 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 3 community issues answered or closed in the last 6 months
- 99 commits in the last 12 weeks
- Last stable release on August 18, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
View related servers

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description must disclose behavioral traits. It only says 'Update', implying mutation, but does not mention permissions, idempotency, side effects, or any constraints. The 'VOICE-FRIENDLY' example adds noise rather than clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with two clear sentences. The 'VOICE-FRIENDLY' line is somewhat extraneous but does not significantly detract. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, all described in schema, the description covers only a subset (title, description, status, custom fields) and ignores x, y, width. An output schema exists but is not referenced. The tool has many siblings; the description fails to provide complete context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by listing updatable fields (title, description, status, custom fields) but omits x, y, width. This partial addition justifies a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'app card', listing specific fields (title, description, status, custom fields). It distinguishes from siblings like miro_update_card by specifying 'app card', though not explicitly contrasting them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., miro_update_card, miro_update_item). The description simply states what it does, omitting context about prerequisites or situational use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as idempotent. The description does not add behavioral details beyond listing updatable fields; it lacks information about error states, partial updates, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, front-loading the purpose. The voice-friendly example is an extra but not essential. Some restructuring could improve clarity, but overall it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and an output schema, the description is too minimal. It does not explain partial update semantics (e.g., omitting a field leaves it unchanged), prerequisites, or the effect of null values. The output schema exists, but the description lacks operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description lists some parameters (title, description, due_date, position) but omits x, y, width, parent_id. The voice-friendly example adds limited value. Baseline 3 is appropriate since schema covers details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a card and lists updatable fields (title, description, due_date, position). It is specific to cards, distinguishing it from generic sibling tools like miro_update_item, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like miro_update_item or miro_update_sticky. There is no mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the annotations. The idempotentHint annotation is present but not referenced. The description adds no information about error handling, side effects, or the effect of omitting optional parameters. The VOICE-FRIENDLY note is not behavioral.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one sentence plus a VOICE-FRIENDLY note. It front-loads the verb and key attributes, but the structure could be improved (e.g., bullet list). There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose but lacks context on behavior (e.g., that unspecified fields remain unchanged) and usage relative to sibling tools. An output schema exists, so return values are not needed. Given the tool's complexity (9 parameters), more context would be beneficial, but the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema already explains each parameter. The description repeats 'url, mode: inline/modal, dimensions, position' but adds no extra meaning. Baseline score of 3 is appropriate as the description provides no additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update' and the resource 'an embed', listing updatable attributes (url, mode, dimensions, position). It is specific but does not explicitly differentiate from sibling update tools for other Miro item types. However, the tool name itself implies the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context for choosing this over sibling tools like miro_update_card or miro_update_sticky.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint but no readOnlyHint or destructiveHint. The description does not disclose behavioral traits beyond stating it's an update, lacking details on side effects, required permissions, or concurrency behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with no redundant words. The two lines convey purpose and an example efficiently. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema, the description lacks context about the effect of updating an image (e.g., replacement vs modification), failure conditions, or relationship to sibling tools. It is incomplete for a tool with 8 parameters and many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal meaning beyond listing field names. Baseline 3 is appropriate as the description summarizes but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an image and lists specific fields (title, url, position, width). However, it does not differentiate this tool from sibling tools like miro_update_image_from_file, which also updates an image but from a file source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about appropriate usage scenarios. The voice-friendly example adds no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The idempotentHint annotation already signals safe retries. The description adds minimal context beyond stating the update action. It does not describe side effects, required permissions, or behavior for null fields. With annotations covering idempotency, a score of 3 reflects adequate but not enhanced transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: one sentence plus a voice-friendly phrase. It is front-loaded and wastes no words. However, the voice-friendly line is somewhat redundant and could be omitted without loss, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 8 parameters and an output schema, the description does not explain critical behavior like partial updates (only non-null fields are updated) or the effect of parent_id. The tool's complexity is higher than what the brief description conveys, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all parameters. The description reiterates a subset (title, url, position, width) but adds no new semantic detail beyond the schema. Baseline 3 is appropriate as the description does not compensate beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a document and lists specific fields (title, url, position, width). The verb-resource pair is unambiguous. However, it does not explicitly differentiate from sibling tools like miro_update_item or miro_update_document_from_file, though the name implies a distinct resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or exclusions (e.g., that other item types have dedicated update tools). This forces the agent to rely solely on naming conventions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no readOnlyHint or destructiveHint, so the description carries full burden. It merely states creation without behavioral details like immediate effect, permissions, limits, or response structure. The VOICE-FRIENDLY gives a sample output but no deeper traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and includes a voice-friendly example. It is efficient, though it could be more structured to mention output schema or behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with 3 parameters (1 required) and an output schema, the description is minimally adequate. It lacks mention of return values, but output schema exists separately, so not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already described. The tool description adds no extra meaning beyond schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Miro board' with a specific verb and resource. It distinguishes from sibling tools like miro_update_board or miro_delete_board. The VOICE-FRIENDLY example adds concrete context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as miro_copy_board or miro_find_board. No prerequisites, exclusions, or context for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies mutation (create), lists allowed colors, and provides an example output. However, it does not disclose permission requirements, board-scoping, or whether the tag is created unattached. With no annotations, the description carries the burden but offers only minimal behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the action. The VOICE-FRIENDLY line is a minor addition but does not detract from clarity. It is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full parameter coverage, the description adequately covers the tool's purpose and inputs. It does not mention post-creation steps (attaching), but for a simple creation tool, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds a list of colors (duplicating schema) and an example voice-friendly message, providing slight reinforcement but no new semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a tag on a Miro board' which is a specific verb and resource. It does not differentiate from siblings like miro_attach_tag, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as miro_attach_tag or miro_update_tag. The description lacks context on the typical workflow of creating and then attaching tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's 'Update' terminology is consistent with the idempotentHint annotation. No additional behavioral traits are disclosed beyond the annotation, which is acceptable but adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two lines. The first line effectively states purpose, but the second line (voice-friendly example) is marginal and could be removed for better conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions only a subset of parameters (content, font_size, color, position) while omitting others like text_align, width, and parent_id. Given the tool has 10 parameters and an output schema exists, the description should cover all updatable attributes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all 10 parameters. The description only lists parameter names without adding new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update) and resource (text element) along with specific attributes (content, font_size, color, position), distinguishing it from sibling tools that update other item types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like miro_update_shape or miro_update_sticky is provided. The description lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds no additional behavioral context beyond the annotation, so it meets the baseline but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and direct, with one main sentence and a voice-friendly example. It is concise, though the voice-friendly part may be unnecessary for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and simple parameters, the description is minimally complete. However, it lacks context to differentiate from similar getter tools or explain when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the input schema. The description adds no extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific app card by ID,' which uses a specific verb and resource, distinguishing it from sibling tools like create, delete, or update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives like miro_get_item or miro_get_board_content, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds minimal behavioral context beyond the fact that it lists connectors. It does not mention pagination behavior (cursor/limit) or that it returns a list, which would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, including a voice-friendly example. Every sentence is relevant and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description does not need to detail return values. It covers the core action of listing connectors on a board. A small mention of pagination would improve completeness, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (limit, cursor, board_id). The description adds no new parameter meaning beyond what the schema provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'connectors (lines/arrows) on a Miro board'. It distinguishes from siblings like miro_create_connector and miro_get_connector by focusing on listing all connectors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., miro_get_connector for a single connector, miro_get_board_content for broader content). The description does not provide when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint annotations, the description carries the burden of behavioral disclosure. It states 'Copy an existing Miro board', which implies a non-destructive read (the original is unchanged) and creates a new board (a write operation). However, it does not mention specific permissions required, rate limits, or what happens to the original board's content (e.g., dependencies on attached items). The description is adequate but minimally informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: one sentence stating the purpose and a voice-friendly example. It is front-loaded with the essential information. The voice-friendly line, while not strictly necessary, provides a concrete illustration. The brevity is effective, though the example could be considered extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, all documented in schema) and the presence of an output schema (as per context signals), the description doesn't need to explain return values. It provides the core functionality. However, it could mention that the copy results in a new board with a new ID, or potential side effects like duplicating content. Still, for a copy operation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description does not add any extra meaning beyond what the schema already provides (e.g., the name defaults to 'Copy of {original}'). Thus, the description adds no value over the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Copy' and the resource 'existing Miro board', making the tool's purpose unmistakable. It distinguishes itself from sibling tools like miro_create_board (which creates a new board from scratch) and miro_find_board/search_board (which locate boards without creating copies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as miro_create_board for a new board or miro_share_board for sharing. There are no exclusions or context about prerequisites (e.g., the user must have access to the original board). The voice-friendly line is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'List' aligns. The voice-friendly example adds a minor behavioral cue about output presentation, but it does not disclose pagination limits or other operational traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence and a voice-friendly example—with no unnecessary words. It is well-structured and easily parseable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be detailed. However, the description lacks mention of pagination behavior, edge cases (e.g., no groups found), or ordering, which are not covered by the schema or annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the parameters. The description adds no additional meaning or context to the parameters (board_id, limit, cursor) beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all groups on a Miro board,' specifying the action (list) and resource (groups on a board). It is distinguishable from sibling tools like miro_create_group and miro_delete_group, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as other list tools (e.g., miro_list_items) or filtering options. No context about prerequisites or exclusion criteria is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks disclosure of behavioral traits beyond the basic action. It does not mention side effects (e.g., overwriting roles, permission requirements, or whether an invitation is sent versus immediate access). With no annotations beyond a title, the description should provide more behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two clear sentences plus a helpful example. It is front-loaded with the main purpose and role details, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the core functionality. However, it omits potential prerequisites (e.g., user must own or have share permissions on the board) and does not reference the output schema that might describe the return value. It is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has descriptions for all 4 parameters (100% coverage). The description adds value by listing the specific roles ('viewer, commenter, editor') and providing a voice-friendly example ('Shared board with jane@example.com as editor'), which enhances semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Share a board with someone by email', specifying the action, resource, and method. It lists the roles (viewer, commenter, editor), distinguishing the invitation action from sibling tools like remove_board_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to use remove_board_member, or prerequisites like board existence). The usage context is implied but not stated, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, so the description adds minimal behavioral context beyond the voice-friendly snippet, which hints at response content but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a voice-friendly example, all front-loaded and without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and simple parameters, the description is sufficient for a straightforward retrieval tool, though it could optionally note error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear descriptions for both parameters; the description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific group by ID', using a specific verb and resource, and differentiating from siblings like miro_get_group_items and miro_list_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to use miro_list_groups instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm readOnlyHint=true. The description doesn't elaborate on pagination behavior (limit/offset) or potential performance implications, though it's consistent with the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes a VOICE-FRIENDLY line that adds minor value; it could be more concise without it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and annotations, the description is fairly complete. However, it lacks notes on error conditions (e.g., invalid board_id) or pagination specifics, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters (board_id, limit, offset) are fully documented in the schema. The description adds no extra semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action is to list users with board access. It clearly distinguishes from sibling tools like miro_get_board_member (singular) and miro_remove_board_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like miro_get_board_member. The VOICE-FRIENDLY line offers a human-readable format hint but doesn't clarify usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
IdempotentHint is already in annotations; description adds a voice-friendly example but does not disclose potential side effects, error handling, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two short sentences, no fluff, and front-loaded purpose. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool with complete schema, output schema, and annotations, description adequately covers purpose and provides a practical example; missing only minor behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters fully (100% coverage); description adds only a minor illustration without new semantic depth, meeting baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update a board member's role' with allowed roles listed, distinguishing it from siblings like remove_board_member or update_board.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs siblings like miro_remove_board_member or other update tools, leaving agents to infer context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation provides idempotentHint=true, indicating safe retries. The description adds no further behavioral details beyond listing updatable fields. It does not disclose side effects, permissions, or partial update behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose and key attributes without any redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterized update tool with a comprehensive input schema and output schema present, the description is sufficient. It could mention partial update behavior, but overall it provides the essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-described parameters. The description merely restates what the schema already provides (e.g., 'style (straight/elbowed/curved)'), adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'connector', and lists specific properties (style, caps, caption, color), distinguishing it from siblings that update different Miro items like boards or cards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not indicate prerequisites, conditions, or scenarios where other tools would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations by revealing cascading effects on children ('Deleting a parent may affect children'), the destructive irreversible nature ('Cannot be undone'), a preview option, and the experimental API version, though it omits authorization or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences and a warning, front-loaded with core action, but could be more compact without losing nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return value explanation is unnecessary. Description covers destructive nature, side effects, and dry_run option adequately for a simple deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so description adds marginal value by reinforcing dry_run usage, but does not provide novel semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a mindmap node' with a specific verb and resource. It also adds context about parent-child effects, but does not explicitly distinguish from sibling delete tools (e.g., miro_delete_app_card).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions using dry_run=true to preview, which provides usage guidance, but does not explicitly specify when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true; description aligns with 'Get details' but adds no extra behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose plus a voice-friendly example. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, 100% schema coverage, and presence of output schema, the description provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions; description does not add additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get details of a specific board member' with a specific verb and resource, distinguishing it from sibling tools like miro_list_board_members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as miro_list_board_members for listing all members or miro_update_board_member for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description reveals it creates a connector (mutation) and lists style/cap options, but does not disclose side effects, failure modes, or that items must be on the same board. No annotations provide behavioral hints, so the description carries the burden but falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states core purpose, second lists configurable options. No redundant words, front-loaded with critical action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters fully described in schema and an output schema present, the description covers the essential action and customization. Missing context about prerequisite item existence or board scope, but acceptable for a straightforward creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds detailed enumerations for style and caps (e.g., 'straight, elbowed (default), curved') beyond the schema's brief phrases, adding value for parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Create a connector line between two items' with clear verb and resource. Lists style and cap options, distinguishing from sibling create tools like miro_create_shape or miro_create_card.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives, no prerequisites mentioned (e.g., items must exist on the board), and no exclusion criteria for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only; description adds no behavioral details 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences plus a voice-friendly example, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description covers essential aspects; missing minor guidance on pagination but schema covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions; description adds no new parameter insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves items within a frame, with filtering ability, and distinguishes from miro_get_group_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides one alternative (miro_get_group_items) but lacks guidance on when to use this versus other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the tool is a read operation, which aligns with the readOnlyHint annotation. No contradiction. However, it adds minimal behavioral context beyond the annotation, such as what fields are returned or any error handling, though 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a short voice-friendly example. No superfluous words, every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with good schema, annotations, and output schema, the description is mostly complete. It covers the basic purpose and parameters, but lacks guidance on error handling or what happens if the tag doesn't exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions ('Board ID', 'ID of the tag to retrieve'). The description does not add meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get details of a specific tag by ID', using a specific verb and resource. It distinguishes from sibling tools like miro_list_tags (list all tags) and miro_get_items_by_tag (get items by tag), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single tag's details by ID, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like miro_list_tags for listing all tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and description adds return type (Markdown, position, timestamps). No contradictions; additional behavioral detail is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with clear sections (purpose, usage, parameters, returns, related). Some redundancy with schema parameter descriptions, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers key return values and usage context. Lacks explanation of 'doc format item' vs other item types, but sibling list provides related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully described in the schema. Description adds no extra meaning beyond labeling them as required, which is already indicated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves a doc format item by ID, with specific verb and resource. However, does not explicitly differentiate from sibling miro_get_document, which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' examples and mentions related tools (miro_create_doc, miro_delete_doc) for context. Does not include when-not-to-use, but sufficient for typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, and the description adds a specific warning about revoking access, which goes beyond the annotation by clarifying the real-world consequence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with purpose, but the voice-friendly phrase is unnecessary for a non-voice context, adding minor bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation (two params, output schema present, annotations provided), the description covers purpose and key consequence. It could mention return value but output schema handles that, so it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions for board_id and member_id. The tool description does not add any additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and resource 'member from a board', distinguishing it from sibling tools like miro_update_board_member which is for updating, not removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a warning but no explicit context on when to use this tool vs alternatives (e.g., miro_update_board_member). Usage is implied through the destructive nature, but no 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fails to disclose behavioral traits beyond the obvious mutation (update). No annotations provide info on idempotency, permissions, or side effects. The VOICE-FRIENDLY snippet adds an example but no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a VOICE-FRIENDLY line, all concise and front-loaded. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, an output schema, and only 2 parameters, the description covers the key constraints (max 20, partial updates). It is mostly complete, though it could mention error handling for partially successful updates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter descriptions, but the description adds semantic value by noting the partial update strategy ('Only provide fields you want to change') which is not captured in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update multiple items at once (max 20)', specifying the verb, resource, and constraint. The tool is distinct from siblings like miro_update_item by targeting multiple items in one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance to 'Only provide fields you want to change' and notes the max 20 limit. While it doesn't explicitly exclude alternatives, the context implies this tool is for bulk updates, leaving single updates to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only a title), so the description carries the burden. It discloses that a frame is a visual container, but does not discuss any behavioral traits such as destructive nature, authorization requirements, rate limits, or side effects. The behavior is predictable as a creation tool, but more detail would benefit the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences that are concise and front-loaded. Every word adds value, with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that all parameters are described in the schema and there is an output schema, the description sufficiently covers the tool's purpose and differentiation from a sibling. It could mention the visual nature more explicitly, but overall it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 7 parameters, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides. It does not explain defaults (e.g., width=800, height=600) or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a frame container to group items visually', specifying the verb 'create', the resource 'frame container', and the purpose 'group items visually'. It also distinguishes from the sibling miro_create_group by noting the difference between visual and logical grouping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides guidance on when to use this tool versus miro_create_group for logical grouping without a visual border. However, it does not mention any other usage contexts, prerequisites, or scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), providing no readOnlyHint or destructiveHint. The description does not disclose behavioral traits such as whether the tool is idempotent, required permissions, or side effects. Given the lack of annotation support, the description should have provided more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a list of use cases. Every sentence provides distinct and valuable information without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, 2 required), the description is fairly complete. It covers purpose, usage, and alternatives. The presence of an output schema reduces the need to explain return values. Minor lack of behavioral transparency prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all 8 parameters described. However, the description adds no additional meaning beyond the schema's minimal descriptions (e.g., 'X position', 'Text color'). Baseline of 3 is appropriate as per guidelines when coverage is high but description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add free-floating text to a Miro board with no background or border.' It explicitly distinguishes this tool from siblings miro_create_sticky and miro_create_doc, providing specific differentiators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use alternatives: 'For notes with colored backgrounds, use miro_create_sticky. For rich Markdown documents, use miro_create_doc.' It also provides example user intents like 'add a title', 'put heading text', which guides the AI agent effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destruction; description adds 'Cannot be undone' and preview suggestion, which are behavioral traits beyond what destructiveHint provides. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, warning, voice-friendly confirmation. No filler, efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and schema covers all parameters, description is fairly complete. The warning and dry_run hint cover the most important behavioral context. Could optionally mention permissions or async behavior, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; description adds the dry_run use case (preview before delete) beyond schema, but no extra meaning for board_id or item_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'Delete an app card from a Miro board' — a specific verb+resource combination that clearly distinguishes it from sibling create and update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a warning about irreversibility and suggests using dry_run=true for preview, which guides usage, but lacks explicit comparison to other delete tools like miro_delete_item or miro_delete_board.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes creation and auto-layout, but no annotations about safety or destructiveness. Limited detail on side effects, limitations, or Mermaid version compatibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with purpose front-loaded. Uses list and code examples efficiently. Minor improvement could group usage guidance more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and param usage, but does not explain output schema or return values. Lacks details on auto-layout behavior, though schema coverage is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear descriptions; the description adds value by providing Mermaid syntax examples and explaining output modes, enriching beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate diagram on Miro from Mermaid code' with examples of use cases and syntax. It differentiates from siblings like miro_create_shape by focusing on bulk diagram generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' phrases covering common diagramming tasks. However, lacks guidance on when not to use it or alternatives like individual item creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds the enterprise restriction, which is important behavioral context. It does not mention error cases (e.g., invalid job_id), but for a simple status check this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The first sentence states the purpose; the second adds a critical constraint. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown) explaining return values. The description covers purpose and enterprise restriction. For a polling tool, it might be helpful to mention retry behavior, but it's not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with basic descriptions. The description adds no extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check' and the resource 'export job progress', distinguishing it from sibling tools like miro_create_export_job and miro_get_export_job_results. The 'ENTERPRISE ONLY' addition provides specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests it's for enterprise use only but does not explicitly state when to use this tool versus miro_get_export_job_results or other polling alternatives. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: true, so the description doesn't need to restate idempotency, but it adds little behavioral context beyond mentioning that image_url can be used for downloading. It could mention permissions or pagination but overall meets minimum adequacy given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two main sentences plus brief examples. No redundant information, and the key purpose is stated upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-details tool with an output schema, the description provides enough context: what it returns, when to use it, and an alternative. It misses nothing critical, though it could mention authentication requirements for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not elaborate on the parameters beyond what is in the schema. Baseline 3 is appropriate since the schema describes both board_id and item_id sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and resource 'image details' including specific outputs (URL, title, dimensions). It explicitly distinguishes from sibling tool 'miro_get_document' for document items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'USE WHEN' section provides concrete examples like 'get image URL' and 'image details', and the 'VOICE-FRIENDLY' example shows a natural query. It also mentions an alternative tool for documents, though it could be more explicit about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by noting it uses a 'v2-experimental API', which informs the agent of potential instability or differences. It does not contradict annotations and provides useful context about the tool's backend.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no redundant information. The first sentence states the core purpose, and the second adds the API version note. Every part is necessary and helps the agent understand the tool quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required params, output schema present, read-only annotation), the description is mostly complete. It could optionally mention that node_id is obtained from list_mindmap_nodes, but that's a minor gap. The experimental API note adds important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for both parameters (board_id and node_id). The description does not add additional meaning or clarify parameter formats beyond what the schema provides, which is acceptable given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'mindmap node', and specifies the details included (content, hierarchy, position). It effectively distinguishes itself from sibling tools like miro_create_mindmap_node and miro_list_mindmap_nodes by indicating it retrieves a single node's details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. However, the purpose is clear enough that an agent can infer its use for retrieving a specific node's data, while listing or creating nodes are handled by siblings. No explicit when-not-to-use or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints (e.g., readOnlyHint, destructiveHint), so the description must fully disclose behavior. It only says 'Add' (implying creation) but omits side effects, permission requirements, success/failure responses, or limits on file size/type. The output schema exists but the description does not reference what happens on completion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the purpose, a key constraint, and an alternative tool. No redundant information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main action and a critical condition, but given the parameter count (7) and the existence of an output schema, it could mention positioning (x, y), parent frame, or result details. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value beyond schema: it clarifies that the URL must be publicly accessible and specifies allowed document types ('PDF, etc.'). These constraints are not present in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add', the resource 'document', and the source 'from a URL'. It specifies document type (PDF, etc.) and the URL accessibility requirement. It distinguishes from the sibling tool miro_upload_document by indicating the alternative for local files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a key precondition (URL must be publicly accessible) and directly points to the alternative tool miro_upload_document for local file uploads. This provides clear guidance on when to use this tool versus its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations beyond title, and description only says 'Create' without detailing side effects, permissions, or limitations. The voice-friendly example adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded with core purpose, then alternatives and use cases. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-item creation tool with output schema, description covers purpose, alternatives, and examples. No gaps given tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, so baseline 3. Description adds example color list and position defaults but no deeper semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a sticky note on a Miro board' and distinguishes from sibling tools like miro_create_sticky_grid and miro_bulk_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit USE WHEN phrases and mentions alternatives, making it clear when to use this tool vs others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and description adds that it performs case-insensitive partial matching, returns board ID. No contradiction; description adds useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded with key purpose. Includes usage examples efficiently. Could be slightly more structured but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameter, output schema exists, and clear purpose, the description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with schema coverage 100%. Description repeats case-insensitivity and partial match already in schema, adding no new meaning. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds a Miro board by name with case-insensitive and partial match, returns board ID, and distinguishes from miro_list_boards which lists all boards. Verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' examples and a voice-friendly response example. Mentions miro_list_boards as alternative for listing all boards, but does not cover edge cases like no match or ambiguous names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, which is the key behavioral trait. The description adds a voice-friendly example of output content but does not elaborate on other behaviors like error handling or response format. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one clear purpose statement and one voice-friendly note. It is compact, front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with a clear purpose, 2 parameters, and an output schema (not shown but present), the description and schema together provide sufficient context. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (board_id and connector_id) with 100% coverage. The tool description does not add any extra meaning or usage guidance for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a specific connector by ID. This distinguishes it from siblings like miro_list_connectors (listing) and miro_create_connector (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: when you need details of a single connector by ID. It does not explicitly exclude cases or name alternatives, but the purpose is clear enough among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds that it uses a v2-experimental API and returns a flat list. This adds value beyond annotations by disclosing the API version and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a distinct purpose: listing the action, explaining output structure, and noting the API version. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination, hierarchy reconstruction), the description covers purpose, output format, and API version. An output schema exists, so return values are not needed. Complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add new information about parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool lists mindmap nodes on a board, which is a specific verb and resource. It clarifies that the output is flat and how to reconstruct hierarchy, distinguishing it from other listing tools like miro_list_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on using parent_id to reconstruct hierarchy but does not explicitly state when to use this tool over alternatives or when not to use it. Sibling tools are not directly comparable, so implied usage is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include idempotentHint; description does not disclose side effects, permission requirements, or whether updates are partial/overwrite. Could add more behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Succinct three-line format with clear sections (description, USE WHEN, VOICE-FRIENDLY); no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks information on prerequisites, error scenarios, and impact on unmentioned fields. Output schema exists but could be more complete for a 9-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions; the description highlights shape and color but adds no novel semantics beyond highlighting type-specificity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a sticky note with type-specific options like shape and color, and explicitly distinguishes from the generic miro_update_item sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not guidance ('For generic updates, use miro_update_item') and lists example use cases via 'USE WHEN' phrases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Adds max-20 constraint but does not disclose atomicity, partial failure behavior, or side effects beyond 'Created 5 items on the board'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences each adding distinct value: purpose+limit, alternative, usage examples. No redundant text, front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema so return values are covered. Missing mention of board existence prerequisite, but overall sufficient for a bulk create tool given schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so all parameters are documented. Description adds max-20 limit and example usage but not extra semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create multiple items at once (max 20)' with a specific verb and resource, explicitly distinguishes from sibling miro_create_sticky_grid via naming.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use advice ('For creating only stickies in a grid, use miro_create_sticky_grid instead') and lists example user queries under 'USE WHEN'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal, so description carries full burden. It states creation but does not disclose side effects, permissions, or error conditions. Basic transparency but no extra context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two brief sentences plus targeted USE WHEN and VOICE-FRIENDLY examples. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, differentiation, and provides example usage. Output schema exists, so return value explanation not needed. Minor gap: no mention of required parameters like board_id, but schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description mentions 'custom fields and status indicators' but does not add meaning beyond the schema definitions. No additional parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an app card with custom fields and status indicators, distinguishing it from miro_create_card for simple cards. The verb 'create' and resource 'app card' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs alternative: 'For simple cards with due dates, use miro_create_card instead.' Also provides 'USE WHEN' phrases, giving clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description must carry the behavioral burden. It states 'Create' (a mutation) but does not disclose side effects, authentication needs, or rate limits. The mention of card features (title, description, due dates) is basic, not behavioral.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences plus USE WHEN and VOICE-FRIENDLY examples. It is front-loaded with the core action and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full schema coverage and an output schema (though not shown), the description is largely complete. It does not describe return values, but output schema likely covers that. It covers purpose, usage, and distinction from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it only reiterates that cards have title, description, and due dates. No parameter-specific extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a card on a Miro board' with a specific verb and resource. It differentiates from the sibling tool miro_create_app_card by noting the latter is for cards with custom fields and status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit USE WHEN examples are given ('add a card', 'create a task card', 'card with due date'). It also specifies when not to use (for custom fields/status, use miro_create_app_card).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses async behavior (returns job ID for monitoring) and enterprise-only restriction. Annotations lack readOnlyHint/destructiveHint, so description compensates by implying non-destructive export. Could mention rate limits or auth details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two impactful sentences with no wasted words. Front-loads purpose and critical constraint (enterprise only).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, async behavior, enterprise restriction, and follow-up step. Output schema exists, so return value details not needed. Complete for a straightforward export job creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes all 4 parameters with full coverage. Description adds no extra parameter details beyond schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Export' and resource 'boards', with specific formats (PDF, SVG, HTML). Differentiates from sibling create tools by focusing on export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes 'ENTERPRISE ONLY', guiding when not to use. Advises to monitor via miro_get_export_job_status, providing post-call guidance. Does not explicitly exclude alternatives, but no competing export tools exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title, so description carries burden. It discloses that grouped items move and resize together, but does not mention permissions, reversibility, or whether original items are modified. Some behavioral context is given but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a voice-friendly line. No filler, every sentence adds value. Action and key differentiator are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with full schema coverage and an existing output schema, the description is largely complete. It explains grouping behavior and differentiates from frame. Minor omission: no mention of whether groups can be nested or modified afterward, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (board_id and item_ids). Description does not add parameter-specific details beyond the schema. Baseline 3 per instructions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: group items logically, and specifies that grouped items move and resize together. It differentiates from miro_create_frame by noting that frame provides a visible container with border and title. The verb 'group' and resource 'items' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly tells when not to use this tool (for a visible container, use miro_create_frame), providing a direct alternative. It also includes a voice-friendly example, guiding the agent on phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no hints (no readonly/destructive), so the description carries the burden. It states 'create' (mutation) and covers parent_id and node_view, but does not disclose error handling, limits, or side effects like ignored x/y for children. Acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no filler. Every word adds value. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's simplicity, the description covers core usage. It could mention board_id context or how to verify creation, but it's sufficient for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining when to use parent_id (root vs child) and providing the default for node_view, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a mindmap node' with a specific verb and resource. It distinguishes from sibling tools like miro_create_card or miro_create_sticky by focusing on mindmap nodes. The details about root vs child nodes further clarify purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear instructions: 'Omit parent_id for root; add parent_id for children' and mentions node_view defaults. It does not explicitly compare to alternatives, but the context of mindmap-specific tools and the name itself guides usage adequately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the destructiveHint annotation by explicitly stating 'Cannot be undone' and recommending dry_run for preview. No contradiction with annotations (destructiveHint: true is consistent).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first efficiently states the purpose, and the second adds a critical warning. Every sentence is necessary and front-loaded, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with an output schema, the description covers the essential purpose, irreversible nature, and dry_run option. However, it could be more complete by clarifying its scope relative to sibling tools (e.g., for generic items vs. specific types), but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the description does not add meaning beyond what the schema already provides. The mention of dry_run in the description aligns with its schema description but doesn't add new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes an item from a Miro board, using a specific verb and resource. Among siblings with many specific delete tools (e.g., delete_app_card, delete_board), this tool is for generic items, distinguishing it effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a warning about irreversibility and recommends using dry_run, but it does not provide guidance on when to use this tool versus alternatives like miro_bulk_delete or other specific delete tools. Usage context is implied but not explicitly contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds the session scope, which is valuable behavioral context. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence front-loading the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the purpose, scope, and filterable fields. With an output schema present, the lack of return format details is acceptable. The session-scope is clearly highlighted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 7 parameters. The description only rephrases the filter options already present in the schema, adding no new semantic insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Query' and the resource 'local audit log for MCP tool executions' with scope 'this session only'. No sibling tool has a similar audit function, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the scope ('this session only'), which helps the agent understand it is for local debugging. It does not provide when-not-to-use or alternatives, but since no other sibling is an audit tool, the lack of exclusion is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true. Description adds behavioral context about the nature of corrections (URLs in ID fields, camelCase keys, etc.) and what is returned (top patterns and recent events), going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an imperative usage directive. Every sentence adds value, and the purpose is front-loaded. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and parameters are well documented, the description explains the concept sufficiently. It could mention pagination or format, but with output schema, it's not strictly necessary. Complete for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description mentions filtering by tool or rule, aligning with parameters, but does not add new meaning beyond implying their use. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries 'desire path normalizations' and shows auto-corrections of tool inputs. It uses specific verbs and resources ('query', 'normalizations', 'auto-corrected'), and distinguishes it from CRUD siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'USE WHEN reviewing tool usage patterns to improve descriptions or schemas,' providing clear context. However, it does not explicitly state when not to use or list alternatives, though the sibling tools list provides implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: enterprise restriction, link expiration, and regeneration. Annotations already indicate read-only (readOnlyHint=true), which is consistent. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences. First states purpose, second adds critical details. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behavioral aspects (enterprise only, expiration) and the existence of an output schema reduces need to explain return values. However, it doesn't mention prerequisites like a completed job, which is slightly implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions ('Export job ID', 'Organization ID'). The description does not add further semantics, but schema coverage is 100%, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves download links for a completed export, using the verb 'Get' and specifying the resource 'download links for completed export'. It distinguishes from siblings like miro_get_export_job_status and miro_create_export_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides key usage context: 'ENTERPRISE ONLY' and 'Links expire in 15 min; call again to regenerate.' It implies when to use (after export completion) and that expiration is handled by re-calling. It doesn't explicitly state when not to use or provide alternatives, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and description reinforces safe reading behavior. It adds context about board ID reuse and includes a voice-friendly example, but does not disclose pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences plus a short example—no redundant words. Front-loaded with core purpose and immediate differentiation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with optional parameters and an output schema, the description covers essential context (scope, sibling differentiation, example). Could mention pagination behavior, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for all 4 parameters, so description does not need to add parameter details. The mention of 'board ID' is useful but not param-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('List') and resource ('Miro boards'), and distinguishes from sibling 'miro_find_board' by specifying that for a specific board by name, the alternative should be used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use `miro_find_board` for name-based search, implying this tool is for general listing. However, it does not cover when to use other listing tools (e.g., `miro_get_board` for single board details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotency, and the description adds the 'at least one field' requirement. However, it does not discuss error cases, authentication needs, or side effects beyond the basic update. The information is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, delivered in two sentences and an example. Every element serves a purpose, and the key information is front-loaded, making it efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (three params, one required) and the presence of an output schema and annotations, the description covers the essential aspects. It might lack details on error handling, but overall it is sufficient for a straightforward update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents each parameter. The description adds value by stating the 'at least one field' constraint and providing a concrete example, enhancing usability beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a Miro board's name or description', specifying the action, resource, and fields involved. Among siblings like miro_update_card or miro_update_frame, this one uniquely targets the board itself, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the important constraint 'At least one field must be provided' and gives a voice-friendly example. Although it does not explicitly list when to use this tool versus others, the sibling tools cover different entity types, making usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, so the safety profile is known. The description adds minimal behavioral context beyond what's in the schema, such as that it updates general attributes without discussing side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus a USE WHEN line, front-loaded with purpose, no unnecessary words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and an output schema, the description adequately covers the general update functionality and points to specialized siblings. It is complete enough for an AI agent to understand when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented in the schema. The description does not add additional meaning beyond paraphrasing 'content, position, or style'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates any item's content, position, or style, and distinguishes itself from siblings by specifying when to use miro_update_sticky, miro_update_card, and miro_update_shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use and when-not-to-use guidance with specific sibling tool names and a dedicated 'USE WHEN' section with example natural language triggers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds that it retrieves 'full details', but does not disclose additional behavioral traits like permissions or rate limits. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two purposeful sentences plus a voice-friendly line. No wasted text; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema, the description covers how to obtain the item ID and provides a usage example. No missing context given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters. The description does not add any extra parameter information beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of a specific item by ID', using a specific verb and resource, and distinguishes from sibling tools like miro_list_items and miro_search_board.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use alternatives: 'If you don't have the item ID, use miro_search_board to find it or miro_list_items to browse.' Also includes a voice-friendly example for natural language queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's added value is minimal. It discloses the return type (list of tags) but no further behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise, using clear sections (USE WHEN, PARAMETERS, RETURNS, RELATED). Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signal), the description sufficiently covers the tool's purpose and usage. No gaps for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptions. The description only restates required status without adding extra semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List tags attached to a specific item', providing a specific verb and resource. It distinguishes from siblings like miro_get_items_by_tag (reverse lookup) and miro_list_tags (all tags).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes 'USE WHEN' section with clear example queries ('what tags are on this sticky', 'show labels for this item'), and explicitly mentions related tool for reverse lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include idempotentHint=true, but the description does not add behavioral details such as side effects or permissions. No contradiction, but no added value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a voice-friendly line; no fluff, effectively front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description focuses on type-specific options, but schema includes generic fields (position, size, parent). This could mislead agents into thinking only shape-specific fields are updatable via this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3); description adds value by highlighting key type-specific parameters and providing a concrete voice-friendly example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a shape with type-specific options and distinguishes it from the sibling tool miro_update_item for generic updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool (type-specific shape updates) and when to use miro_update_item (generic updates).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, consistent with the update operation. The description adds the constraint that at least one of title or color must be provided, which is beyond annotations. No contradictions or missing behavioral details for the simple operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a voice-friendly example. Every sentence adds value: purpose, constraint, and an example for voice interfaces. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 params, 2 required, 100% schema coverage, output schema exists), the description is fully adequate. It covers purpose, constraint, and provides an example. Siblings are differentiated by object type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented. The description adds the cross-parameter constraint that at least one of title or color must be provided, which is not obvious from the schema alone. This adds meaningful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it updates a tag's title or color, which is a specific verb and resource. It clearly distinguishes from sibling tools like miro_list_tags (listing) and other update tools (different object types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage constraint ('At least one must be provided') but lacks explicit guidance on when to use this tool versus alternatives. Sibling names provide implicit differentiation, but no when-not-to-use or explicit comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description clearly indicates a create operation (embedding), but lacks details on permissions or side effects. No annotations beyond title, so description is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, uses bullet points for usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main use case and includes examples. With output schema present, return details are implicit. Minor gap: does not explicitly state that board_id and url are required, but schema handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds limited value beyond schema. It lists supported URL providers, which aids understanding but is not critical.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool embeds external content as live preview, lists specific providers, and distinguishes from sibling tools like miro_create_image and miro_create_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' examples and alternatives, making it easy for an agent to decide when to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a key behavioral trait: max 50 stickies. The VOICE-FRIENDLY example hints at the output format. However, with no annotations beyond title, it could disclose more about potential side effects or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: only three sentences plus structured USE WHEN and VOICE-FRIENDLY sections. It is front-loaded with the core purpose and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, usage guidelines, constraints, and an example output. With output schema existing, return values are covered. However, it omits details like grid layout behavior (e.g., row filling) and default parameter values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters. The description adds little extra meaning beyond the schema, though the VOICE-FRIENDLY example indirectly references columns. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create multiple sticky notes arranged in a grid layout (max 50).' It distinguishes itself from the sibling miro_bulk_create by advising 'For mixed item types, use miro_bulk_create.' The USE WHEN phrases further clarify the specific use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios via USE WHEN phrases and gives an alternative tool for mixed item types. While it doesn't mention miro_create_sticky, the grid layout implies it's for multiple items, and the max limit is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: explains permanence and preview option. No contradiction with destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then essential warning. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavioral aspects (permanence, preview) and has output schema. Missing permissions or ownership requirements, but sufficient for a simple delete tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds emphasis on dry_run but no new semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Delete' and resource 'board permanently'. Distinguishes from sibling tools like miro_delete_item because it specifies deletion of the board itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns that the action cannot be undone and recommends using dry_run=true to preview. Does not compare to alternatives like miro_delete_item, but provides clear safety guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true. The description adds context about what is returned (items by type, frame hierarchy, connectors, tags) and includes a voice-friendly output example, complementing the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus a USE WHEN phrase and a voice-friendly example. Information is front-loaded, every sentence adds value, and there is no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to detail return values. It covers purpose, usage, alternative, and gives a sample output. Could mention pagination or limits, but max_items parameter addresses that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not significantly add beyond the schema. It implies the boolean parameters by mentioning connectors and tags, but does not explain max_items or provide additional parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get all board content' and the resource, and distinguishes from sibling 'miro_get_board_summary' by specifying that this is for full content for AI analysis and documentation generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit USE WHEN phrases like 'analyze this board', 'generate documentation', and provides an alternative: 'For a quick summary, use miro_get_board_summary instead.' This tells the agent exactly when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, and the description adds that it returns counts and statistics. Slightly unclear on what 'statistics' includes, but overall good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, front-loaded with action, alternative, use cases, and example - no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with one param and an output schema, the description covers purpose and usage well, but could detail output format more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (board_id) with 100% schema coverage; description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a board overview with item counts and statistics, and distinguishes it from miro_get_board_content for full content export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use this tool via trigger phrases and directs to an alternative for different needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, so the description's behavioral disclosure is less critical. It adds context by stating it returns URL and title, and includes a voice-friendly example. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences covering purpose, usage, and a voice-friendly example. No redundant words; front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description need not detail return values. It covers purpose, usage, and alternative tools sufficiently. Slightly lacking in edge-case information but complete for a straightforward get tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add parameter meaning beyond what the schema provides. Baseline 3 is appropriate as no additional param details are offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a document on a Miro board, including its Miro-hosted URL and title,' using a specific verb and resource. It distinguishes from the sibling tool miro_get_image by explicitly noting when to use that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' phrases such as 'get document details', 'what document is this', and 'document URL', guiding the agent on appropriate contexts. Also indicates when not to use (for image items).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that items are listed with a max of 50 and supports pagination via cursor, but does not detail response sorting or ordering. Consistent and informative enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a brief 'USE WHEN' line. Every part adds value without redundancy, and the key info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% coverage), output schema, and annotations, the description covers purpose, limitations, and alternatives. It doesn't mention response ordering, but that is not critical for tool selection. Adequate for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-described in the input schema. The description reiterates the limit but adds no new meaning beyond what the schema provides. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists items on a Miro board with a maximum of 50 items. It distinguishes itself from siblings 'miro_list_all_items' (auto-pagination) and 'miro_search_board' (text search), making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: use 'miro_list_all_items' for all items with auto-pagination and 'miro_search_board' for text search. The 'USE WHEN' line gives practical examples, aiding correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide a title, so the description carries the behavioral burden. It reveals prerequisites (tag must exist), supported item types (sticky_note, card), and a voice-friendly output example. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences for core purpose, then structured USE WHEN, FAILS WHEN, and VOICE-FRIENDLY sections. Every sentence adds value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, failure cases, and usage examples. With an output schema present, return values are handled separately. All necessary context for a simple attachment tool is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds context: tag_id must exist on the board, and item_id must be a sticky_note or card (schema restricts to sticky note, description adds card). This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool attaches an existing tag to a sticky note or card, specifying verb, resource, and target. It distinguishes from siblings like miro_create_tag and miro_detach_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage examples and failure conditions are provided. It explains when it fails (tag doesn't exist, wrong item type) and implies using miro_create_tag first. Could be slightly more explicit about alternatives like miro_detach_tag for removal, but overall clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, description adds 'Cannot be undone' and advises dry_run for safety, fully disclosing behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, with purpose and warning front-loaded. The voice-friendly line is extraneous but not distracting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects: purpose, limits, safety, and parameter hint. With output schema present, return values need not be explained. Sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers parameters (100% coverage), but description adds value by explaining dry_run's purpose and confirming the 20-item limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool deletes multiple items at once with a max of 20, distinguishing it from single-item delete or other bulk operations among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear warning about irreversibility and recommends using dry_run for preview, guiding safe usage. Could explicitly mention alternatives but not necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description carries the transparency burden. It discloses the operation (create), supported Markdown elements, and a voice-friendly confirmation message. It does not mention authorization or side effects, but the context is straightforward for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (USE WHEN, PARAMETERS, EXAMPLE, RELATED, VOICE-FRIENDLY) and front-loaded main sentence. No redundant information, though sections like PARAMETERS partially overlap with schema. Efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description does not need to explain return values. It covers purpose, usage context, parameter behavior, examples, and related tools. Missing error handling or permission details, but sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by listing `board_id`, `content`, `x`, `y`, `parent_id` with brief meanings, notes that `content` supports specific Markdown features, and includes a concrete example. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), resource (rich text document on Miro board), and input format (Markdown). It distinguishes from sibling 'miro_create_document' which is for URL-based documents, and 'miro_create_text' for plain text, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' section listing typical user prompts like 'add a document' or 'create a doc from markdown', and a 'RELATED' section naming alternatives such as miro_get_doc, miro_delete_doc, and miro_create_document, clearly guiding when to use vs. other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral constraints (publicly accessible URLs) and aspect ratio preservation. Annotations are minimal, so description carries burden; could mention error handling or idempotency but covers key trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded key info, no redundant sentences. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists (not needed in description), all 7 parameters covered, usage guidelines and behavioral note present. Complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions; description restates parameters without adding significant new meaning beyond the schema, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and resource 'image to a Miro board from a URL', distinguishing it from siblings like miro_upload_image for local files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'USE WHEN' trigger phrases and a 'RELATED' alternative (miro_upload_image), providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description adds valuable context: 'Cannot be undone' and recommendation to use dry_run. However, it does not mention error handling (e.g., if connector not found) or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences, includes a clear warning, and is front-loaded. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with an output schema and three parameters, the description covers purpose, irreversible effect, and a preview option. It is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions dry_run in the warning but does not add additional meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a connector from a Miro board,' which is a specific verb+resource+scope. It easily distinguishes from sibling tools like miro_create_connector and miro_update_connector.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'WARNING: Cannot be undone. Use dry_run=true to preview first.' This tells when to use (with precaution) and suggests an alternative approach (dry_run) to test without consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses that the tag is removed from all items (a key side effect) and emphasizes irreversibility, adding valuable behavioral context not in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three short sentences covering action, warning, and voice-friendly response. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers essential context: what it does, side effects (removes from items), irreversibility, and a safe usage tip. With an existing output schema, return value details are unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters (100% coverage). The description only reiterates the dry_run usage, adding no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete a tag from a board) and the scope (removes from all items), distinguishing it from siblings like miro_create_tag, miro_attach_tag, and miro_update_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that the action cannot be undone and suggests using dry_run=true to preview, giving practical usage guidance. However, it does not explicitly contrast with alternative tag tools or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tag remains on the board for reuse, which is a key behavioral trait beyond the minimal annotations (only title). It does not mention permissions or idempotency, but for a simple detach operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a usage line, no redundancy, front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full schema coverage, and presence of output schema, the description covers all necessary context: what the tool does, how it differs from sibling (miro_delete_tag), and example commands.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so the parameters are already well-documented. The description adds no additional parameter-level details beyond usage examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and resource 'tag from a sticky note or card'. It distinguishes from deletion by noting the tag stays on the board, and provides example usage phrases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'USE WHEN' section with concrete examples and explicitly directs to miro_delete_tag for full deletion, providing clear guidance on when to use this tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, so description focuses on additional context: works for all Miro plans and a voice-friendly confirmation. Adds value without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a voice-friendly line. No fluff, information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, annotations, and output schema, description covers purpose, scope, and alternatives. Sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with board_id description. Description does not add parameter details beyond schema, but hints at output type (preview image URL). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'preview image URL for a board'. Distinguishes from sibling tools like miro_get_board that return board data, not image URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: get preview image only. Provides alternative for full exports: 'For full PDF/SVG exports, use the Enterprise export tools.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds that it returns 'full details', and the voice-friendly example hints at output content (size, item count). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: two main sentences plus a one-line voice-friendly example. Every sentence adds value: purpose, sibling guidance, and a concrete output example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 required params, output schema present, annotations provided), the description is complete. It explains the purpose, directs to sibling, and provides an example. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage with clear parameter descriptions. The description reinforces that frame_id is for a 'specific frame' but does not add new semantic details beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Get full details of a specific frame by ID'. It uses a specific verb ('Get') and resource ('frame'), and distinguishes from sibling tool 'miro_get_frame_items' by explicitly directing to that tool for items inside.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (get frame details) and provides a clear alternative for a different use case: 'To get items inside the frame, use miro_get_frame_items'. This helps the agent select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior (readOnlyHint=true). The description adds context by mentioning 'with their details' and a voice-friendly example, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: two sentences plus a voice-friendly note. Front-loaded with the primary purpose, then an alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage guidance, and provides an example output. With an output schema present, return values are not needed. Complete for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema. The description adds minimal parameter-specific value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves items in a group with their details, using specific verb and resource. It also distinguishes from a sibling (miro_get_frame_items) explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names an alternative tool for frame items, providing clear guidance on when to use this tool vs. others. No when-not-to-use conditions, but the sibling differentiation is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true; description adds return content details and usage patterns (IDs used with other tools), enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-loaded with core purpose, followed by usage guidance and voice-friendly example; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple list operation, description covers return fields, usage with siblings, and has output schema; no gaps for an agent to correctly select and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions; description does not add further semantics beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'List' and resource 'tag definitions on a board' with clear output fields (IDs, titles, colors). Distinguishes from siblings by focusing on listing tags only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides USE WHEN examples ('show all tags', 'what tags exist') and a concrete scenario (before attaching a tag to get its ID), aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context: search is case-insensitive. Annotations already indicate read-only. No contradictions. While it doesn't detail limits or errors, the added voice-friendly example and case-insensitivity are helpful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences plus a usage block and voice-friendly example. No wasted words, well-structured with clear sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. The description covers purpose, usage guidelines, behavioral context, and provides examples. It is complete for a search tool with good sibling distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description does not add significant new semantic details beyond what the schema provides, making the contribution marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (search), resource (items on a board), and distinguishes from sibling tool miro_list_items for listing without search. The description is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use examples ('find items about X', 'search for budget') and an explicit alternative for non-search listing. Also includes a voice-friendly output example, guiding the agent on expected response format.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is a mutation (update) and notes the required constraint. Annotations already provide idempotentHint=true, and the description adds context about the VOICE-FRIENDLY format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus a VOICE-FRIENDLY example. Every sentence adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage and an output schema, the description is sufficient. It covers allowed fields and a key constraint, leaving no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds the constraint 'At least one field must be provided', which goes beyond the schema's required parameters and clarifies usage. This extra guidance justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a frame's title, position, size, or color, specifying the verb 'update' and the resource 'frame'. It distinguishes from sibling tools like miro_update_sticky by being specific to frames.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a guideline that at least one optional field must be provided, which helps avoid invalid calls. It does not explicitly compare to alternatives, but the context of frames is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the operation is a complete replacement and imposes a minimum item constraint. Annotations already indicate idempotency; description adds behavioral detail without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with no wasted words. Uses two sentences plus a voice-friendly confirmation example. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (3 parameters, straightforward replacement), the description fully covers the behavior and constraints. An output schema exists, so return values are documented elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaningful context beyond the schema: explains the replacement behavior and minimum item requirement for item_ids. Schema already covers parameter names and descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a group's member items') and resource, distinguishing it from sibling update tools for different Miro items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides key usage guidance: replacing all members and including existing IDs to keep them, plus a minimum item count. Does not explicitly state when not to use or name alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds critical details beyond destructiveHint annotation: items are ungrouped, operation cannot be undone, and suggests dry_run preview. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences covering purpose, warning, and voice-friendly feedback with no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers behavior, safety, and usage; missing mention of prerequisites like valid board_id, but sufficient for a delete operation given output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters; description adds context for dry_run parameter, enhancing understanding beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a frame' and distinguishes behavior by noting items inside are not deleted but ungrouped, differentiating it from siblings like miro_delete_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides cautionary note about irreversibility and recommends dry_run=true for preview, but does not explicitly contrast with alternative deletion tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that it returns a list of items with IDs, types, and content, and mentions pagination (limit/offset). It does not contradict annotations. Could mention permission requirements, but overall adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (USE WHEN, PARAMETERS, RETURNS, RELATED). Informationally dense but no unnecessary fluff. Minor redundancy (limit max 50 appears twice) but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (so return details are covered), the description covers purpose, parameters, related tools, use cases, and even provides a voice-friendly example. Very complete given the tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage. The description adds value by explaining default/max values for limit, clarifying tag_id is required and how to get it via miro_list_tags, and noting offset is for pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all items with a specific tag on a board, with concrete examples ('show items tagged Urgent'). It distinguishes from sibling tools like miro_get_item_tags (reverse lookup) and miro_attach_tag/detach_tag (management).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a 'USE WHEN' section with relevant user queries. Guides the agent to miro_list_tags for obtaining tag IDs and notes alternatives like miro_get_item_tags for reverse lookup, providing clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide a title; no behavioral hints. Description clarifies the operation is a replacement (destructive), requires the item to already exist, and requires the file to be on the local filesystem. Could be more explicit about side effects on the old file, but sufficiently transparent for the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise and well-structured: front-loaded with core action, followed by usage guidelines, parameter list with brief explanations, notes, related tools, and a voice-friendly summary. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, and related tools. With an output schema present, return values need not be described. Lacks explicit error handling or file validation details, but is otherwise complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds supported file formats for file_path (png, jpg, jpeg, gif, webp, svg) and clarifies parameter roles (e.g., title as alt text, parent_id as frame to move into), providing value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Replace the file on an existing image item with a new local image file,' providing a specific verb and resource. It distinguishes from siblings by explicitly naming miro_update_image (for metadata only) and miro_upload_image (for creating new images).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a 'USE WHEN' section with example user phrases and clear alternatives: 'For updating metadata only, use miro_update_image instead' and 'To create a new image from file, use miro_upload_image.' Provides precise context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description carries the burden. It discloses that the tool uses the v2-experimental API and that shape types may change when moving to GA. While it doesn't discuss permissions or side effects, the experimental warning adds important behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: overall description, USE WHEN, PARAMETERS, and NOTE. It is concise with no redundant sentences, and each section is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not explain return values. It covers purpose, usage guidelines, experimental API warning, and parameter details comprehensively. The description is complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by listing supported shape types, providing example hex values for fill_color and border_color, and mentioning default sizes. This goes beyond the schema descriptions, helping the agent understand valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: to create a flowchart shape using the experimental API, and it distinguishes from the sibling tool miro_create_shape by noting it supports additional stencil shapes beyond standard shapes. The verb 'create' and resource 'flowchart shape' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'USE WHEN' conditions, listing user phrases that should trigger this tool, and directly states that for standard shapes, use miro_create_shape instead. This gives clear guidance on when to use the tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack behavioral hints, so the description carries the burden. It describes the creation action, required parameters, and return values (item ID, shape type, position, size, view link). However, it does not mention permissions or side effects, which would be beneficial but not critical for a straightforward creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (USE WHEN, SHAPE TYPES, PARAMETERS, RETURNS, RELATED, EXAMPLE). It is concise yet informative, with no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters (2 required), the description covers all essential aspects: purpose, shape categories, parameter descriptions, defaults, return type, and a related tool. The example further aids understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by grouping shape types (Basic, Flow, Flowchart) and providing default values for width, height, x, y. It also includes an example showing parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a shape on a Miro board' and lists specific shape types. It distinguishes from sibling tool miro_create_flowchart_shape, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'USE WHEN' triggers (e.g., 'add a rectangle') and points to an alternative tool for flowchart-specific shapes, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, and the description adds a clear warning that the action cannot be undone and recommends using dry_run=true to preview. This provides important behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, parameters, warning, and related tools. It conveys all essential information in a concise, front-loaded format with no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation, the description covers purpose, usage guidelines, parameters, and important warnings. Since an output schema exists, the lack of return value explanation is acceptable. The context is complete for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond what the schema already provides. The description lists parameters with similar wording, but does not add new semantic depth or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a doc format item from a Miro board, using a specific verb and resource. It distinguishes from sibling tools like miro_delete_item by specifying 'doc format item' and mentions related tools miro_get_doc and miro_create_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'USE WHEN' triggers such as 'remove the document' and 'delete that doc'. Provides warning about irreversibility, suggests dry_run for preview, and directs to miro_get_doc for inspection before deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant value beyond the destructiveHint annotation by explaining the default behavior (items released), warning that item deletion is irreversible, and suggesting a dry_run preview. All behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, organized into clear sections (USE WHEN, WARNING, VOICE-FRIENDLY). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All necessary aspects are covered: purpose, usage, parameter behavior, and important warnings. The description is complete for confident tool invocation, given the supporting schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description enhances understanding by clarifying the effect of delete_items (default false) and how dry_run works, providing practical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a group' and distinguishes between two modes: deleting only the group (ungrouping items) or deleting both group and items. This differentiates from sibling tools like miro_delete_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage scenarios ('USE WHEN: deleting a group OR ungrouping items') and explains the behavior of the delete_items parameter with default values. While it doesn't mention alternatives explicitly, the guidance is clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds useful context about what metadata is returned and provides a voice-friendly example, but does not significantly expand beyond annotation. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, parameter details, return info, and a voice-friendly example. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given existence of output schema, description appropriately covers purpose, usage, parameter sourcing, and return types. Complements sibling context and annotations fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single parameter board_id with description 'Board ID to retrieve'. Description adds value by stating it is required and suggesting sources (miro_list_boards or miro_find_board).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves board metadata (name, description, owner, creation date, sharing policy) and explicitly distinguishes from sibling tools miro_get_board_summary and miro_get_board_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit USE WHEN examples ('who owns this board?', etc.) and NOT FOR cases with specific alternative tools (miro_get_board_summary, miro_get_board_content).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title). The description adds useful behavioral context: file must exist locally, supported formats, max 6 MB, and that the item must already be a document. However, it does not disclose whether the operation is destructive or reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (USE WHEN, PARAMETERS, NOTE, RELATED, VOICE-FRIENDLY). Front-loaded with purpose, no irrelevant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters (3 required) and an output schema exists, the description covers purpose, parameter constraints, usage context, and related tools thoroughly. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by specifying supported file formats and max size for file_path, and clarifying that item_id refers to an existing document item. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it replaces the file on an existing document item with a new local file. It distinguishes from siblings (miro_update_document for metadata only, miro_upload_document for creating new).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'USE WHEN' examples (replace this document, update the PDF, swap the file) and explicitly contrasts with alternative tools for different use cases (metadata updates, creation).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide a title, so the description bears responsibility. It discloses file size limit (6 MB), supported formats, requirement for local file, and notes about remote documents. While it could mention what happens on failure or permissions, it reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: main sentence, USE WHEN, PARAMETERS, NOTE, RELATED, VOICE-FRIENDLY. It is informative without being verbose, every section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and presence of an output schema, the description covers all necessary aspects: purpose, parameter details, usage context, file constraints, alternatives, and expected feedback. It is complete for an AI agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by specifying valid file formats and size limit for file_path, noting x/y as position, and parent_id as frame. This enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Upload a local document file to a Miro board'), clearly indicating the verb, resource, and scope. It differentiates from siblings like miro_upload_image (for images) and miro_create_document (for remote URLs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'USE WHEN' section listing user phrases such as 'upload this document', and explicitly tells when to use alternatives (miro_upload_image for images, miro_create_document for remote URLs). This provides clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations beyond title, the description carries full burden. It reveals that the tool uploads a local file (mutation), supports specific image formats, requires file existence on filesystem, and is distinct from document/remote uploads. Lacks details on overwrite behavior or error outcomes, but sufficient for safe selection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections (USE WHEN, PARAMETERS, NOTE, RELATED, VOICE-FRIENDLY). Each sentence adds value, no fluff. Front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, an output schema, and sibling tools, the description covers usage context, parameter details, constraints (local file only, formats), and relationships to other tools. Very complete for an upload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions, so baseline is 3. The description adds value by listing supported extensions for file_path, clarifying title as alt text, and providing overall context for each parameter. This extra detail justifies a score above 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uploads a local image file to a Miro board, and explicitly differentiates from miro_upload_document (for documents) and miro_create_image (for remote images), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit USE WHEN phrases ('upload this image', 'add screenshot to board'), distinguishes between image vs document uploads, and mentions alternative for remote images (miro_create_image). Also includes a RELATED section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses automatic pagination, a maximum of 10000 items, and provides a voice-friendly example. Since annotations already include readOnlyHint=true, the description adds further behavioral context (pagination behavior and limits) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three main sentences plus a usage phrase and a voice-friendly mock output. Every sentence provides necessary information, and the key action is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and thorough annotations, the description is complete. It covers the tool's purpose, usage guidelines, behavioral traits (pagination, limit), and provides a sample output. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by highlighting the automatic pagination and the max_items limit (up to 10000), which reinforces the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves ALL items from a board with automatic pagination up to 10000, and explicitly contrasts with the sibling tool miro_list_items for quick lookups (max 50). This provides a specific verb+resource+scope and distinguishes from similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('get everything on board', 'list all items', 'export board contents') and when not to (for quick lookups max 50, use miro_list_items instead), providing clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![miro-mcp-server MCP server](https://glama.ai/mcp/servers/olgasafonova/miro-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/olgasafonova/miro-mcp-server)

Score Badge

Copy to your README.md:

[![miro-mcp-server MCP server](https://glama.ai/mcp/servers/olgasafonova/miro-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/olgasafonova/miro-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/olgasafonova/miro-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server